go-music-api#

Use this skill to install and run a local go-music-api backend, search tracks across sources, download audio, embed metadata, and recover from source failures.

Primary workflow#

Prefer the bundled scripts instead of reimplementing the flow by hand.

Route by platform#

• On Linux or macOS, use scripts/install.sh and scripts/play.sh.
• On Windows, read docs/windows.md before proceeding.
• When the user mentions cookies, VIP-only tracks, grey tracks, or login-required tracks, read docs/cookies.md.

Linux/macOS install#

Run:

bash

scripts/install.sh

The install script should:

• install go-music-api into ~/.openclaw/music
• choose a usable local port
• start the backend in the background
• verify health with a local API request

Linux/macOS download#

Run:

bash

scripts/play.sh "稻香" "$HOME/.openclaw/media/daoxiang.mp3"

The play script should:

• search by query
• handle nested search payloads such as data.data, data.list, or data.songs
• rank candidates by song title, artist, and source quality
• avoid karaoke, cover, remix, live, DJ, and instrumental variants when possible
• download the audio stream to the requested path
• reuse cached files when an equivalent file already exists
• call scripts/embed_metadata.py to write title, artist, album, cover art, and embedded lyrics when available

Prefer saving final media under a sendable location such as ~/.openclaw/media/.

Manual API workflow#

Use this only for debugging or when the helper scripts need changes.

1. Ensure the backend is installed and running.
2. Read ~/.openclaw/music/port on Linux/macOS or %USERPROFILE%\.openclaw\music\port on Windows; default to 8080 if absent.
3. Search with GET /api/v1/music/search?q={q}.
4. Parse list results from the top-level response or nested data.* collections.
5. Choose the best candidate.
6. Download audio with GET /api/v1/music/stream?id={id}&source={source}.
7. Treat the stream response as audio bytes, not JSON.
8. If playback fails, try GET /api/v1/music/switch?... to switch source and retry.
9. If user provides account cookies, read docs/cookies.md, set them with POST /api/v1/system/cookies, and verify with GET /api/v1/system/cookies.
10. Fetch lyrics with GET /api/v1/music/lyric?id={id}&source={source} when needed.

Files and state#

Runtime files live under ~/.openclaw/music (Linux/macOS) or %USERPROFILE%\.openclaw\music (Windows):

• binary: go-music-api (Linux/macOS) or go-music-api.exe (Windows)
• log: log.txt
• pid: pid
• port: port
• cache index: cache-index.json

Failure handling#

• If installation fails, check platform and architecture detection, GitHub Releases reachability, and required tools such as curl, tar, unzip, and file (Linux/macOS) or the Windows requirements in docs/windows.md.
• Match release asset names exactly. Do not use loose matching that could select .deb or .rpm packages.
• Accept only native executables after extraction. Fail immediately for text files, HTML, scripts, or package files. On Windows, validate the PE header (MZ signature).
• If metadata embedding is required, ensure Python and mutagen are available. If not, skip metadata embedding or install the dependency before retrying.
• If certain tracks fail due to platform restrictions, ask for platform cookies and apply them via /api/v1/system/cookies before switching sources.
• If startup health checks fail, inspect the runtime log.txt.
• If the backend always binds to a fixed port in practice, simplify the port logic instead of pretending dynamic ports work.