ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

xiaomusic 定时任务配置指南:基于 Crontab 语法实现小爱音箱的自动播放、关机与语音播报

xiaomusic 定时任务配置指南:基于 Crontab 语法实现小爱音箱的自动播放、关机与语音播报 xiaomusic 定时任务配置指南基于 Crontab 语法实现小爱音箱的自动播放、关机与语音播报【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic本指南围绕 xiaomusic 项目的定时任务crontab配置功能展开讲解如何用标准 crontab 表达式驱动小爱音箱在指定时刻自动播放歌曲、播放列表、执行关机、文字转语音TTS、刷新曲库、调整音量等操作。读完本文你将掌握定时任务的完整配置格式、所有受支持任务类型的参数语义以及工作日/休息日限定执行等进阶用法可直接落地为可运行的配置文件。定时任务是什么功能定位与配置入口在 xiaomusic 中定时任务是一段 JSON 数组配置每一条记录描述在什么时间、对哪台设备、执行什么操作。系统采用标准 crontab 表达式描述执行时机由 APScheduler 的AsyncIOScheduler调度器驱动见 crontab.py 中Crontab类的实现。该配置的核心应用场景包括工作日早晨定时播放叫醒歌曲随后自动关机每晚固定时间播放指定歌单、播报语音提醒每天凌晨自动刷新音乐列表、重新初始化登录态以缓解风控/登录失效问题按法定工作日/休息日差异化调度需结合项目内置的节假日数据。配置入口主要有两个Web 设置页面在crontab_json文本框中粘贴 JSON 配置setting.html 中即为该表单项环境变量XIAOMUSIC_CRONTAB_JSON见 config.py 中crontab_json: str os.getenv(XIAOMUSIC_CRONTAB_JSON, )的定义。保存配置后xiaomusic.update_config_from_setting()会调用self.crontab.reload_config(self)见 xiaomusic.py重新加载所有定时任务无需重启进程即可生效。配置格式JSON 数组与核心字段定时任务整体是一个 JSON 数组数组中的每个对象代表一条任务。以官方文档 docs/issues/182.md 给出的完整示例为基础最简任务形如[ { expression: 0 8 * * 0-4, name: play, did: 123456789, arg1: 周杰伦晴天 } ]字段语义字段必填含义expression是标准 crontab 表达式描述任务的执行时机name是任务类型目前仅支持下文列出的若干固定值did视任务而定小爱音箱的设备 ID即设置页面中音箱型号后面的那串数字arg1视任务而定任务参数含义随name不同而不同crontab 表达式说明expression遵循标准 crontab 五段式格式分 时 日 月 周。需要注意星期字段的取值约定星期一是 0星期二是 1星期日是 6。 取值范围为0-6也支持mon,tue,wed,thu,fri,sat,sun这类英文缩写写法一周的第一天固定是 Monday。例如0 8 * * 0-4表示周一至周五每天 8 点30 10 * * *表示每天 10 点 30 分。加载与调度流程源码视角从源码看定时任务从配置到执行的调用链为crontab.pyreload_config()读取config.crontab_json用json.loads解析为任务列表对每条任务调用add_job_cron()按name动态拼接方法名add_job_{name}并通过getattr分发到对应的任务注册函数每个注册函数内部定义async def job()再交给add_job()注册到AsyncIOScheduleradd_job()将 crontab 表达式解析为CronTrigger并设置了三个关键调度参数coalesceTrue若任务错过多次触发只补执行一次适合播放类任务max_instances30同一任务最多允许 30 个并发实例支持多设备并发misfire_grace_time60任务延迟 60 秒内仍会执行。此外若配置开启了enable_auto_clean_temp系统还会在每次加载时自动附加一个每日凌晨 3 点清理临时文件的任务。支持的任务类型总览当前支持以下任务类型对应name取值name功能是否需要 didarg1 含义stop关机是无play播放歌曲是歌曲名play_music_list播放列表是播放目录名可用\|追加目录内歌曲名play_music_tmp_list播放自定义列表是临时歌单名称可选tts文字转语音是要播报的语音文字refresh_music_list刷新播放列表否无set_volume设置音量是音量值0–100set_play_type设置播放类型是0–4 的数字set_pull_ask设置是否拉取对话记录否enable/disablereinit重新初始化否无set_play_type的arg1取值与播放类型的对应关系arg1播放类型0单曲循环1全部循环2随机播放3单曲播放4顺序播放在 crontab.py 中add_job_set_play_type会执行play_type int(arg1)后调用xiaomusic.set_play_type(did, play_type, False)播放类型的枚举常量定义于 config.pyPLAY_TYPE_ONE/ALL/RND/SIN/SEQ。完整配置示例与逐条解读官方文档给出的完整示例覆盖了全部任务类型配置如下[ { expression: 0 8 * * 0-4, name: play, did: 123456789, arg1: 周杰伦晴天 }, { expression: 10 8 * * 0-4, name: stop, did: 123456789 }, { expression: 0 9 * * *, name: play, did: 123456789, arg1: 周杰伦晴天 }, { expression: 0 10 * * *, name: play_music_list, did: 123456789, arg1: 周杰伦 }, { expression: 30 10 * * *, name: play_music_list, did: 123456789, arg1: 周杰伦|晴天 }, { expression: 0 7 * * *, name: tts, did: 123456789, arg1: 早上好该起床了 }, { expression: 0 3 * * *, name: refresh_music_list }, { expression: * * * * *, name: set_volume, did: 123456789, arg1: 25 }, { expression: * * * * *, name: set_play_type, did: 123456789, arg1: 2 }, { expression: 0 6 * * *, name: set_pull_ask, arg1: enable }, { expression: 0 0 * * *, name: set_pull_ask, arg1: disable }, { expression: 0 1 * * *, name: reinit }, { expression: 33 20 * * *, name: play_music_tmp_list, did: 978479727, arg1: 临时列表1, music_list: [ 1大青树下的小学, 7听听秋的声音, 11宝葫芦的秘密 ], first: 11宝葫芦的秘密 } ]上述配置的逐条含义周一至周五每天 8 点播放歌曲周杰伦晴天周一至周五每天 8 点 10 分执行关机指令每天 9 点播放歌曲周杰伦晴天每天 10 点播放列表周杰伦每天 10 点 30 分播放列表周杰伦里的晴天play_music_list的arg1用|分隔目录名与歌曲名每天 7 点发出语音早上好该起床了每天 3 点刷新播放列表用于自动更新音乐目录下的歌曲到播放列表每分钟设置音量为 25每分钟设置为随机播放每天早上 6 点开启拉取对话记录每天晚上 12 点关闭拉取对话记录每天 1 点重新初始化晚上 8 点 33 分将 3 首歌曲组成名为临时列表1的临时歌单并从11宝葫芦的秘密开始播放其中arg1与first均为可选字段。各任务类型深入解析play定时播放歌曲add_job_play内部调用xiaomusic.play(did, arg1)。从 xiaomusic.py 的实现看play还支持用|分隔搜索关键词和显示名称parts arg1.split(|)第一个元素作为搜索关键词第二个元素作为歌曲名称缺省时名称即关键词。play_music_list定时播放列表add_job_play_music_list调用xiaomusic.play_music_list(did, arg1)。在 xiaomusic.py 中arg1以|拆分为列表名与可选歌曲名最终经do_play_music_list校验列表存在性后交给设备播放器执行若列表不存在音箱会 TTS 播报播放列表xx不存在。play_music_tmp_list定时播放自定义临时歌单这是把多首歌曲临时拼成一个歌单播放的任务也是结构最特殊的一条crontab.py 中add_job_play_music_tmp_listarg1临时歌单名称可选缺省为crontab_tmp_listmusic_list歌曲名数组必填first起始播放的歌曲名可选。其执行流程为先通过music_library.play_list_update_music(name, music_list)以覆盖方式写入自定义歌单歌单不存在则自动新建见 music_library.py再调用do_play_music_list(did, name, music_name)从指定歌曲开始播放。tts定时语音播报add_job_tts调用xiaomusic.do_tts(did, arg1)将arg1的文字内容通过小爱音箱播报出来适合做起床提醒、整点报时等场景。refresh_music_list定时刷新曲库add_job_refresh_music_list调用xiaomusic.gen_music_list()用于自动更新音乐目录下的歌曲到播放列表。从 music_library.py 看刷新时会按配置的music_path、music_path_depth目录深度、exclude_dirs排除目录以及SUPPORT_MUSIC_TYPE支持的音频扩展名重新遍历音乐目录并重建列表。若设置了enable_file_watch目录监控新增歌曲可被自动感知而定时刷新则是一种不依赖监控的兜底方案。set_volume定时设置音量add_job_set_volume调用xiaomusic.set_volume(did, arg1)arg1为 0–100 的整数音量值。示例中* * * * *即每分钟执行一次可用于持续校正音量。set_play_type定时切换播放模式add_job_set_play_type将arg1转为整数后调用xiaomusic.set_play_type(did, play_type, False)第三个参数False表示切换时不做 TTS 语音播报。对应关系见上文表格0 单曲循环 / 1 全部循环 / 2 随机播放 / 3 单曲播放 / 4 顺序播放。set_pull_ask定时开关对话记录拉取add_job_set_pull_ask通过arg1为enable或disable直接切换config.enable_pull_ask布尔值其余值一律视为关闭。该开关控制是否向小爱音箱拉取对话记录官方文档提示每天定时关闭可缓解风控问题因此常见做法是白天开启、夜间关闭如示例中 6 点 enable、0 点 disable。reinit定时重新初始化add_job_reinit调用xiaomusic.reinit()。在 xiaomusic.py 中reinit会重新初始化日志、调用auth_manager.init_all_data()重建登录认证数据并重新生成音乐列表与播放列表。官方文档建议每天执行一次以缓解登录失效问题。stop定时关机add_job_stop调用xiaomusic.stop(did, notts)notts参数表示关机前不做 TTS 播报。典型组合是工作日 8 点播放叫醒歌曲 8 点 10 分关机让音箱完成叫醒后自动进入待机。进阶用法按工作日/休息日限定执行针对工作日执行、休息日不执行的需求项目在 crontab.py 中实现了CustomCronTrigger自定义触发器支持在expression末尾追加特殊注释标记末尾加#workday仅在法定工作日执行末尾加#offday仅在法定休息日执行含法定节假日与周末。示例[ { expression: 0 8 * * * #workday, name: play, did: 123456789, arg1: 周杰伦晴天 }, { expression: 0 10 * * * #offday, name: play, did: 123456789, arg1: 周杰伦晴天 } ]其实现原理是CustomCronTrigger.get_next_fire_time()先用基础CronTrigger算出下一个候选触发时间再根据标记调用 holiday.py 中的is_working_day()或is_off_day()校验当天是否满足条件若不满足则递归寻找下一个候选时间。节假日判断依赖仓库holiday/目录下按年份组织的 JSON 数据如 holiday/2025.json数据加载逻辑见load_year_data()优先查表判定法定调休日表中没有的日期则按周末周六、周日判定。因此该功能可直接覆盖春节、国庆等法定节假日以及调休上班日比单纯用 crontab 的星期字段精确得多。Crontab.add_job()中会检测expression是否包含workday/offday标记自动选用CustomCronTrigger还是标准CronTrigger用户无需手动指定。配置校验与排障建议JSON 合法性定时任务是整段 JSON 数组任何语法错误都会导致reload_config解析失败。建议先用 JSON 校验工具检查配置是否合法后再粘贴到设置页。表达式合法性非法 crontab 表达式会在注册时抛出ValueError日志中输出Invalid crontab expression ...该任务会被跳过不影响其他任务注册。name 拼写add_job_cron按add_job_{name}反射调用name不在支持列表时日志会报object has no attribute add_job_xxx任务不生效。did 归属did必须对应当前设备列表中的音箱 ID即设置页面音箱型号后的那串数字填写错误会导致任务找不到设备。日志观察每次加载成功都会打印crontab reload_config ok及每条任务注册信息crontab add_job_cron ok. did:... name:... arg1:... expression:...可据此确认任务是否被正确解析。运行时状态set_pull_ask、set_play_type等状态类任务会实时修改运行内存中的配置配合 Web 设置页可以观察对应开关的实际状态。小结xiaomusic 的定时任务功能把标准 crontab 语法与音箱控制命令完整打通一份 JSON 数组即可编排播放、关机、播报、刷新曲库、调整音量/播放模式、开关对话拉取、重新初始化等全部受支持操作并可借助#workday/#offday标记叠加法定节假日判断实现贴近真实生活的作息自动化。相关实现均可对照 crontab.py、holiday.py、xiaomusic.py 与 music_library.py 等源码深入研读。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表