拓冰网站定制 
web-to-app 背景音乐BGM功能详解播放模式、LRC 同步歌词与 APK 加密打包【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app本文基于 web-to-app 仓库的 BGM 官方文档 与对应源码系统讲解如何在生成的应用中配置带同步歌词的背景音乐从「编辑通用配置」中的 BGM 卡片各选项到BgmConfig数据模型、BgmPlayer播放引擎的三种播放模式实现、LRC 歌词的解析与持久化规则再到音频文件打包进导出 APK 时的加密与解密链路。读完本文你可以完整掌握该功能的配置方法、参数含义与底层实现机制。BGM 卡片的位置与核心选项BGM 功能入口位于 编辑通用配置编辑器 中的背景音乐卡片用于在生成的应用里播放背景音乐并显示同步歌词。卡片对应 UI 实现为 BgmCard.kt。文档定义了五个选项启用—— 打开背景音乐对应数据模型中的bgmEnabled字段见 WebApp.kt#L107-L108默认false。播放列表—— 添加音乐曲目支持同步LRC 歌词与歌词动画。播放模式—— 循环、顺序或随机BgmPlayMode。随机模式首曲即随机每轮每首播一次不重复播完重洗。歌词样式—— 自定义字体、颜色、描边和阴影。在线搜索—— 在线搜索音乐。数据模型BgmConfig、BgmItem与播放模式所有配置收敛在 WebApp.kt 中定义的一组数据类上。WebApp应用模型通过bgmEnabled是否启用与bgmConfig具体配置两个字段持有 BGM 状态。BgmConfig播放器配置定义见 WebApp.kt#L1162-L1169字段与默认值如下字段类型默认值含义playlistListBgmItem空列表播放列表为空时播放器直接返回不播放playModeBgmPlayModeLOOP循环 / 顺序 / 随机volumeFloat0.5f音量取值 0~1autoPlayBooleantrue初始化后是否自动开唱首曲showLyricsBooleantrue是否显示歌词lrcThemeLrcTheme?null歌词样式主题BgmItem曲库条目BgmItemWebApp.kt#L1149-L1160描述单首曲目name曲目名、path音频路径、coverPath封面可选、isAsset是否为 assets 预置曲目、tags曲风标签、lrcData解析后的歌词等。path的取值有两种形态这也是后续解密链路分叉的根源asset:///bgm/xxx.mp3—— 预置在 APK assets 中的音乐绝对路径如/data/user/0/.../files/bgm/xxx.mp3—— 用户导入的音乐文件。BgmPlayMode与随机模式的「洗牌」语义BgmPlayMode枚举包含LOOP、SEQUENTIAL、SHUFFLE三个值WebApp.kt#L1042-L1046。文档中「随机模式首曲即随机每轮每首播一次不重复播完重洗」的完整实现在 BgmPlayer.kt 中首曲即随机initialize()在配置为SHUFFLE时立即生成shuffledIndices playlist.indices.shuffled()BgmPlayer.kt#L67-L69因此第一轮第一首就是随机抽中的每轮不重复播放索引currentIndex在洗牌数组上顺序前进playCurrentTrack()通过shuffledIndices[currentIndex]映射回真实曲目BgmPlayer.kt#L80-L83保证一轮内不重复播完重洗playNext()中索引取模回绕到 0 时重新shuffled()BgmPlayer.kt#L153-L164开启新一轮洗牌。另外两种模式的细节LOOP循环单曲列表时直接置isLooping true交给MediaPlayer硬件级循环多曲时每首播完调用playNext()轮转BgmPlayer.kt#L101、BgmPlayer.kt#L127-L135。SEQUENTIAL顺序按列表顺序播放末曲播完后回到第一首继续BgmPlayer.kt#L136-L145。进度上报由主线程Handler每 100ms 轮询MediaPlayer.currentPosition并回调onProgressListenerBgmPlayer.kt#L33-L47供歌词高亮与进度条使用。LRC 歌词格式解析、旁挂持久化与样式解析规则LRC 文本解析在 BgmStorage.parseLrcText() 中完成使用两条正则时间戳行[mm:ss.xx]歌词毫秒支持两位或三位(\d{2,3})元数据行[ti:标题]、[ar:歌手]、[al:专辑]大小写不敏感。每行解析为LrcLine(startTime, endTime, text, translation?)。endTime的推断策略是先默认给 5000ms 的占位时长随后统一把每一行的endTime修正为下一行的startTimeBgmStorage.kt#L491-L493即「当前句持续到下一句开始」这正是歌词高亮换行的时间依据。LrcLine还带可选的translation字段支撑歌词翻译场景。旁挂sidecar持久化文档强调歌词和标签的修改会持久化到曲库旁挂.lrc与标签文件即使曲目尚未保存进应用配置刷新和重启后依然保留。对应实现.lrc旁挂文件路径由 getLrcPathForBgm() 统一约定用户音乐与其同目录同名的.lrcassets 预置音乐因为 assets 只读改写为写入filesDir/bgm/同名.lrc扫描时优先采用该用户覆盖版本BgmStorage.kt#L81-L93。保存歌词时通过 saveLrc() 重写标准 LRC 文本其中翻译行以「同一时间戳双行」形式写出注释说明这与导出管线ApkBuilder.convertLrcDataToLrcString的 wire 格式保持一致保证翻译在旁挂文件往返中不丢失。曲风标签BgmTag如PURE_MUSIC、ANIME、SLEEP等见 WebApp.kt#L1048-L1092不随曲目配置保存而是集中持久化在曲库级文件bgm/library_tags.json中键为asset/曲目名或user/曲目名saveTagsForBgm()。源码注释解释了这样设计的原因否则标签只存在于恰好引用了该曲目的应用配置里重新扫描就会丢失。歌词的编辑与手动对齐入口在 UI 层的 LrcEditorDialog.kt 与 ManualLrcAligner.kt。歌词样式LrcTheme文档中的「歌词样式 —— 自定义字体、颜色、描边和阴影」对应 LrcTheme字段默认值含义fontFamilydefault字体fontSize18f字号textColor#FFFFFF普通歌词颜色highlightColor#FFD700当前句高亮颜色backgroundColor#80000000背景色半透明黑strokeColor/strokeWidthnull/0f描边颜色与宽度shadowEnabledtrue是否启用阴影animationTypeFADE歌词动画类型positionBOTTOM歌词位置TOP/CENTER/BOTTOMshowTranslationtrue是否显示翻译歌词动画类型枚举 LrcAnimationType 提供 7 种NONE、FADE、SLIDE_UP、SLIDE_LEFT、SCALE、TYPEWRITER打字机、KARAOKE卡拉 OK 逐字高亮即文档所说的「歌词动画」。曲库扫描assets 预置与用户导入曲库扫描由 BgmStorage.scanAllBgm() 完成合并两个来源assets 预置曲库app/src/main/assets/bgm/目录。其 README.txt 定义了预置文件的命名规则音乐文件小乔.mp3封面图片小乔.png或.jpg/.jpeg同名音乐与图片自动配对图片作为封面图标显示封面可选仅用于选择界面识别示例小乔.mp3 小乔.png、背景音乐1.mp3 背景音乐1.jpg、bgm_01.mp3无封面。用户曲库应用私有目录filesDir/bgm/通过 scanUserBgm() 扫描封面与 LRC 均按同名旁挂匹配。两个扫描器对音频格式的约定一致即 MUSIC_EXTENSIONSmp3、m4a、aac、ogg、flac、wav—— 与文档「在线音乐搜索按真实格式下载曲目 —— MP3、M4A、AAC、OGG、FLAC 或 WAV —— 都会出现在选择器中」的描述完全吻合。封面识别扩展名为png/jpg/jpeg/jpe/jfif/webp/bmp/gif/heic/heif且jpeg/jpe/jfif会规范化为jpgnormalizeCoverExtension()。用户从系统导入音频时saveBgm() 会把 ContentResolver 中的 URI 拷贝为bgmDir/安全文件名.mp3文件名经sanitizeBgmName()清洗仅保留字母、数字、中文、_、-空白时回退为bgm_UUID并在写入后校验文件非空。封面保存 saveCover() 会先删除旧扩展名的同名文件再写入扩展名解析顺序为 MIME → URI 路径提示 → 文件头魔数支持识别 JPEG/PNG/GIF/WEBP/BMP 头最终兜底jpg。选择器 UI 实现在 BgmSelector.kt运行时展示则挂载在壳应用界面ShellBgmPlayer.kt由 ShellScreen.kt 等壳组件装配。在线音乐搜索「在线搜索」选项的 API 与下载逻辑位于core/bgm包下的 OnlineMusicApi.kt 与 OnlineMusicDownloader.ktUI 入口为 OnlineMusicSearchDialog.kt。下载的曲目按真实音频格式落盘只要扩展名在上述MUSIC_EXTENSIONS六者之列就会在下次曲库扫描中进入选择器——这就是文档中「按真实格式下载曲目都会出现在选择器中」的保证机制。BGM 在导出 APK 中的打包与加密文档说明「BGM 音频文件被打包进导出的 APK并可加密」这条链路在 BgmPlayer.setAssetDataSource() 中完整可见播放asset:///路径的曲目时先探测是否存在assetPath.enc加密副本有加密副本通过AssetDecryptor.loadAsset()解密为字节流写入cacheDir下临时文件命名bgm_hash.mp3随后用本地文件路径喂给MediaPlayer。临时文件缓存在tempFileCache中同一曲目反复切歌不再重复解密release()时统一清理临时文件BgmPlayer.kt#L315-L337无加密副本直接assets.openFd()获取AssetFileDescriptor以 fd 偏移 长度方式设置数据源避免整文件读入内存。用户曲目非 asset 路径则直接setDataSource(绝对路径)播放不参与 assets 打包。另外bgmEnabled还会影响导出 APK 的运行时权限集合RuntimePermissionSync.kt#L88 处按「若bgmEnabled则追加相应权限」的逻辑参与权限同步保证生成应用具备播放所需的系统权限。小结web-to-app 的 BGM 功能是一条完整的「配置 → 曲库 → 播放 → 导出」链路配置侧bgmEnabled开关 BgmConfig播放列表、BgmPlayMode、音量、自动播放、歌词显示、LrcTheme样式曲库侧assets 预置app/src/main/assets/bgm/同名配对封面与用户目录filesDir/bgm/双来源扫描支持六种音频格式、多格式封面识别、LRC 旁挂与library_tags.json标签持久化刷新和重启后修改不丢失播放侧BgmPlayer基于MediaPlayer实现循环 / 顺序 / 洗牌随机三种模式随机模式保证「首曲随机、每轮不重复、播完重洗」导出侧音频打入 APK assets 并支持.enc加密运行时解密到缓存播放关键源码入口一览BgmPlayer.kt、BgmStorage.kt、WebApp.ktBGM 数据模型、BgmCard.kt、assets/bgm 预置说明。【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 web-to-app 背景音乐（BGM）功能详解：播放模式、LRC 同步歌词与 APK 加密打包
web-to-app 背景音乐BGM功能详解播放模式、LRC 同步歌词与 APK 加密打包【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app本文基于 web-to-app 仓库的 BGM 官方文档 与对应源码系统讲解如何在生成的应用中配置带同步歌词的背景音乐从「编辑通用配置」中的 BGM 卡片各选项到BgmConfig数据模型、BgmPlayer播放引擎的三种播放模式实现、LRC 歌词的解析与持久化规则再到音频文件打包进导出 APK 时的加密与解密链路。读完本文你可以完整掌握该功能的配置方法、参数含义与底层实现机制。BGM 卡片的位置与核心选项BGM 功能入口位于 编辑通用配置编辑器 中的背景音乐卡片用于在生成的应用里播放背景音乐并显示同步歌词。卡片对应 UI 实现为 BgmCard.kt。文档定义了五个选项启用—— 打开背景音乐对应数据模型中的bgmEnabled字段见 WebApp.kt#L107-L108默认false。播放列表—— 添加音乐曲目支持同步LRC 歌词与歌词动画。播放模式—— 循环、顺序或随机BgmPlayMode。随机模式首曲即随机每轮每首播一次不重复播完重洗。歌词样式—— 自定义字体、颜色、描边和阴影。在线搜索—— 在线搜索音乐。数据模型BgmConfig、BgmItem与播放模式所有配置收敛在 WebApp.kt 中定义的一组数据类上。WebApp应用模型通过bgmEnabled是否启用与bgmConfig具体配置两个字段持有 BGM 状态。BgmConfig播放器配置定义见 WebApp.kt#L1162-L1169字段与默认值如下字段类型默认值含义playlistListBgmItem空列表播放列表为空时播放器直接返回不播放playModeBgmPlayModeLOOP循环 / 顺序 / 随机volumeFloat0.5f音量取值 0~1autoPlayBooleantrue初始化后是否自动开唱首曲showLyricsBooleantrue是否显示歌词lrcThemeLrcTheme?null歌词样式主题BgmItem曲库条目BgmItemWebApp.kt#L1149-L1160描述单首曲目name曲目名、path音频路径、coverPath封面可选、isAsset是否为 assets 预置曲目、tags曲风标签、lrcData解析后的歌词等。path的取值有两种形态这也是后续解密链路分叉的根源asset:///bgm/xxx.mp3—— 预置在 APK assets 中的音乐绝对路径如/data/user/0/.../files/bgm/xxx.mp3—— 用户导入的音乐文件。BgmPlayMode与随机模式的「洗牌」语义BgmPlayMode枚举包含LOOP、SEQUENTIAL、SHUFFLE三个值WebApp.kt#L1042-L1046。文档中「随机模式首曲即随机每轮每首播一次不重复播完重洗」的完整实现在 BgmPlayer.kt 中首曲即随机initialize()在配置为SHUFFLE时立即生成shuffledIndices playlist.indices.shuffled()BgmPlayer.kt#L67-L69因此第一轮第一首就是随机抽中的每轮不重复播放索引currentIndex在洗牌数组上顺序前进playCurrentTrack()通过shuffledIndices[currentIndex]映射回真实曲目BgmPlayer.kt#L80-L83保证一轮内不重复播完重洗playNext()中索引取模回绕到 0 时重新shuffled()BgmPlayer.kt#L153-L164开启新一轮洗牌。另外两种模式的细节LOOP循环单曲列表时直接置isLooping true交给MediaPlayer硬件级循环多曲时每首播完调用playNext()轮转BgmPlayer.kt#L101、BgmPlayer.kt#L127-L135。SEQUENTIAL顺序按列表顺序播放末曲播完后回到第一首继续BgmPlayer.kt#L136-L145。进度上报由主线程Handler每 100ms 轮询MediaPlayer.currentPosition并回调onProgressListenerBgmPlayer.kt#L33-L47供歌词高亮与进度条使用。LRC 歌词格式解析、旁挂持久化与样式解析规则LRC 文本解析在 BgmStorage.parseLrcText() 中完成使用两条正则时间戳行[mm:ss.xx]歌词毫秒支持两位或三位(\d{2,3})元数据行[ti:标题]、[ar:歌手]、[al:专辑]大小写不敏感。每行解析为LrcLine(startTime, endTime, text, translation?)。endTime的推断策略是先默认给 5000ms 的占位时长随后统一把每一行的endTime修正为下一行的startTimeBgmStorage.kt#L491-L493即「当前句持续到下一句开始」这正是歌词高亮换行的时间依据。LrcLine还带可选的translation字段支撑歌词翻译场景。旁挂sidecar持久化文档强调歌词和标签的修改会持久化到曲库旁挂.lrc与标签文件即使曲目尚未保存进应用配置刷新和重启后依然保留。对应实现.lrc旁挂文件路径由 getLrcPathForBgm() 统一约定用户音乐与其同目录同名的.lrcassets 预置音乐因为 assets 只读改写为写入filesDir/bgm/同名.lrc扫描时优先采用该用户覆盖版本BgmStorage.kt#L81-L93。保存歌词时通过 saveLrc() 重写标准 LRC 文本其中翻译行以「同一时间戳双行」形式写出注释说明这与导出管线ApkBuilder.convertLrcDataToLrcString的 wire 格式保持一致保证翻译在旁挂文件往返中不丢失。曲风标签BgmTag如PURE_MUSIC、ANIME、SLEEP等见 WebApp.kt#L1048-L1092不随曲目配置保存而是集中持久化在曲库级文件bgm/library_tags.json中键为asset/曲目名或user/曲目名saveTagsForBgm()。源码注释解释了这样设计的原因否则标签只存在于恰好引用了该曲目的应用配置里重新扫描就会丢失。歌词的编辑与手动对齐入口在 UI 层的 LrcEditorDialog.kt 与 ManualLrcAligner.kt。歌词样式LrcTheme文档中的「歌词样式 —— 自定义字体、颜色、描边和阴影」对应 LrcTheme字段默认值含义fontFamilydefault字体fontSize18f字号textColor#FFFFFF普通歌词颜色highlightColor#FFD700当前句高亮颜色backgroundColor#80000000背景色半透明黑strokeColor/strokeWidthnull/0f描边颜色与宽度shadowEnabledtrue是否启用阴影animationTypeFADE歌词动画类型positionBOTTOM歌词位置TOP/CENTER/BOTTOMshowTranslationtrue是否显示翻译歌词动画类型枚举 LrcAnimationType 提供 7 种NONE、FADE、SLIDE_UP、SLIDE_LEFT、SCALE、TYPEWRITER打字机、KARAOKE卡拉 OK 逐字高亮即文档所说的「歌词动画」。曲库扫描assets 预置与用户导入曲库扫描由 BgmStorage.scanAllBgm() 完成合并两个来源assets 预置曲库app/src/main/assets/bgm/目录。其 README.txt 定义了预置文件的命名规则音乐文件小乔.mp3封面图片小乔.png或.jpg/.jpeg同名音乐与图片自动配对图片作为封面图标显示封面可选仅用于选择界面识别示例小乔.mp3 小乔.png、背景音乐1.mp3 背景音乐1.jpg、bgm_01.mp3无封面。用户曲库应用私有目录filesDir/bgm/通过 scanUserBgm() 扫描封面与 LRC 均按同名旁挂匹配。两个扫描器对音频格式的约定一致即 MUSIC_EXTENSIONSmp3、m4a、aac、ogg、flac、wav—— 与文档「在线音乐搜索按真实格式下载曲目 —— MP3、M4A、AAC、OGG、FLAC 或 WAV —— 都会出现在选择器中」的描述完全吻合。封面识别扩展名为png/jpg/jpeg/jpe/jfif/webp/bmp/gif/heic/heif且jpeg/jpe/jfif会规范化为jpgnormalizeCoverExtension()。用户从系统导入音频时saveBgm() 会把 ContentResolver 中的 URI 拷贝为bgmDir/安全文件名.mp3文件名经sanitizeBgmName()清洗仅保留字母、数字、中文、_、-空白时回退为bgm_UUID并在写入后校验文件非空。封面保存 saveCover() 会先删除旧扩展名的同名文件再写入扩展名解析顺序为 MIME → URI 路径提示 → 文件头魔数支持识别 JPEG/PNG/GIF/WEBP/BMP 头最终兜底jpg。选择器 UI 实现在 BgmSelector.kt运行时展示则挂载在壳应用界面ShellBgmPlayer.kt由 ShellScreen.kt 等壳组件装配。在线音乐搜索「在线搜索」选项的 API 与下载逻辑位于core/bgm包下的 OnlineMusicApi.kt 与 OnlineMusicDownloader.ktUI 入口为 OnlineMusicSearchDialog.kt。下载的曲目按真实音频格式落盘只要扩展名在上述MUSIC_EXTENSIONS六者之列就会在下次曲库扫描中进入选择器——这就是文档中「按真实格式下载曲目都会出现在选择器中」的保证机制。BGM 在导出 APK 中的打包与加密文档说明「BGM 音频文件被打包进导出的 APK并可加密」这条链路在 BgmPlayer.setAssetDataSource() 中完整可见播放asset:///路径的曲目时先探测是否存在assetPath.enc加密副本有加密副本通过AssetDecryptor.loadAsset()解密为字节流写入cacheDir下临时文件命名bgm_hash.mp3随后用本地文件路径喂给MediaPlayer。临时文件缓存在tempFileCache中同一曲目反复切歌不再重复解密release()时统一清理临时文件BgmPlayer.kt#L315-L337无加密副本直接assets.openFd()获取AssetFileDescriptor以 fd 偏移 长度方式设置数据源避免整文件读入内存。用户曲目非 asset 路径则直接setDataSource(绝对路径)播放不参与 assets 打包。另外bgmEnabled还会影响导出 APK 的运行时权限集合RuntimePermissionSync.kt#L88 处按「若bgmEnabled则追加相应权限」的逻辑参与权限同步保证生成应用具备播放所需的系统权限。小结web-to-app 的 BGM 功能是一条完整的「配置 → 曲库 → 播放 → 导出」链路配置侧bgmEnabled开关 BgmConfig播放列表、BgmPlayMode、音量、自动播放、歌词显示、LrcTheme样式曲库侧assets 预置app/src/main/assets/bgm/同名配对封面与用户目录filesDir/bgm/双来源扫描支持六种音频格式、多格式封面识别、LRC 旁挂与library_tags.json标签持久化刷新和重启后修改不丢失播放侧BgmPlayer基于MediaPlayer实现循环 / 顺序 / 洗牌随机三种模式随机模式保证「首曲随机、每轮不重复、播完重洗」导出侧音频打入 APK assets 并支持.enc加密运行时解密到缓存播放关键源码入口一览BgmPlayer.kt、BgmStorage.kt、WebApp.ktBGM 数据模型、BgmCard.kt、assets/bgm 预置说明。【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考