Music Assistant

控制您的 Music Assistant 服务器，实现音乐播放、队列管理和曲库浏览。

设置

使用此技能前，需要配置 Music Assistant 连接：

bash

必需

export MAURL=http://YOURSERVER_IP:8095/api
export MATOKEN=YOURBEARER_TOKEN

可选 - 未设置时将自动检测

export MAPLAYER=yourplayer_id

获取令牌：

1. 1. 打开 Music Assistant 网页界面
2. 进入 设置 → 安全
3. 创建或复制您的长期访问令牌

获取播放器 ID：
bash
./scripts/mactl.py players

快速开始

bash

基本控制

./scripts/mactl.py play # 播放/暂停切换
./scripts/mactl.py next # 跳过曲目
./scripts/mactl.py volume 75 # 设置音量为 75%

搜索并播放

./scripts/mactl.py search nirvana ./scripts/mactl.py play-search pink floyd # 搜索并播放第一个结果

查看当前播放内容

./scripts/mactl.py status ./scripts/mactl.py queue

播放控制

bash
./scripts/mactl.py play # 播放/暂停切换
./scripts/mactl.py pause # 暂停
./scripts/mactl.py stop # 停止播放
./scripts/mactl.py next # 下一曲
./scripts/mactl.py prev # 上一曲

音量

bash
./scripts/mactl.py volume 75 # 设置音量 0-100
./scripts/mactl.py mute # 静音
./scripts/mactl.py unmute # 取消静音

队列管理

bash
./scripts/mactl.py shuffle true # 启用随机播放
./scripts/mactl.py shuffle false # 禁用随机播放
./scripts/mactl.py repeat all # 重复模式（关闭|全部|单曲）
./scripts/mactl.py clear # 清空队列
./scripts/mactl.py queue-items # 列出队列内容

搜索与播放

bash

搜索曲库

./scripts/mactl.py search pink floyd
./scripts/mactl.py search nirvana --type track album
./scripts/mactl.py search metallica --limit 5

搜索并立即播放第一个结果

./scripts/mactl.py play-search smells like teen spirit ./scripts/mactl.py ps comfortably numb # 简写

通过 URI 播放（用于脚本/高级使用）

./scripts/mactl.py play-uri spotify://track/4gHnSNHs8RyVukKoWdS99f

状态与信息

bash
./scripts/mactl.py status # 显示播放器状态 + 当前播放
./scripts/mactl.py queue # 队列状态
./scripts/mactl.py recent # 最近播放的项目
./scripts/mactl.py players # 列出所有可用播放器

曲库

bash
./scripts/mactl.py sync # 触发曲库同步

示例

播放一些涅槃乐队的歌
bash
./scripts/mactl.py play-search nirvana

现在在播放什么？
bash
./scripts/mactl.py status

跳过这首曲目
bash
./scripts/mactl.py next

将音量设置为 50%
bash
./scripts/mactl.py volume 50

开启随机播放
bash
./scripts/mactl.py shuffle true

直接 API 访问

对于 CLI 未涵盖的操作，可直接使用 JSON-RPC API：

bash
curl -s http://YOUR_SERVER:8095/api \
-H Content-Type: application/json \
-H Authorization: Bearer $MA_TOKEN \
-d {messageid:1,command:playerqueues/all}

API 文档地址：http://YOUR_SERVER:8095/api-docs

关键 API 命令

命令	参数	描述
players/all	-	列出所有播放器
player_queues/all

- | 列出所有队列 | | playerqueues/playpause | queue_id | 切换播放/暂停 | | playerqueues/next | queueid | 下一曲 | | playerqueues/previous | queueid | 上一曲 | | playerqueues/stop | queueid | 停止播放 | | playerqueues/shuffle | queueid, shuffle_enabled | 设置随机播放 | | playerqueues/repeat | queueid, repeat_mode | 设置重复模式（关闭/全部/单曲） | | playerqueues/clear | queueid | 清空队列 | | playerqueues/items | queueid, limit, offset | 获取队列项目 | | playerqueues/playmedia | queue_id, uri | 通过 URI 播放 | | music/search | search, media_types, limit | 搜索曲库 | | music/recentlyplayeditems | limit | 最近播放项目 | | music/sync | media_types, providers | 同步曲库 | | config/players/get | player_id | 获取播放器设置 |