qq-music-control（QQ 音乐控制）

QQ Music Browser Control

Use this community-maintained skill to control QQ Music's web player (y.qq.com) through a browser DevTools/CDP endpoint.

Security model

This skill uses the Chrome DevTools Protocol (CDP) to automate QQ Music's web UI. It is not affiliated with Tencent or QQ Music. CDP is a powerful protocol — the following safeguards are in place to minimize its blast radius:

Domain whitelist

The script only operates on y.qq.com tabs. Two layers of domain validation are enforced:

1. Target selection: When choosing which tab to connect to, the script checks the tab URL against an allow-list (y.qq.com). Non-matching tabs are rejected.
2. Pre-evaluate re-check: Immediately before every Runtime.evaluate call, the script queries location.hostname of the connected page and verifies it is still y.qq.com. If the page has navigated to a different domain since connection, the call is rejected with an error.

This prevents the script from reading or manipulating content on other websites (email, banking, etc.), even if the page navigates away after the initial connection.

Isolated browser profile (recommended)

We strongly recommend launching the browser with --user-data-dir pointing to a dedicated directory:

chrome --remote-debugging-port=9222 --user-data-dir=/path/to/qq-music-profile

This ensures:

• The CDP-enabled browser instance has no access to your main browser's cookies, passwords, or sessions
• Only QQ Music login state exists in this profile
• Closing this browser leaves your main browser unaffected

Single-port binding

The script probes only one port by default — read from .cdp-port cache file, or falling back to 9222. It does not scan port ranges. This minimizes the chance of accidentally connecting to unrelated DevTools endpoints.

No SSRF policy changes required

This skill does not use OpenClaw's built-in browser tool. It connects to CDP directly via WebSocket from a local Node.js script. No SSRF policy relaxation is needed in OpenClaw's configuration.

What CDP can and cannot do

Honest limitations

• CDP inherently has access to all tabs in the connected browser. The domain whitelist is an application-level guard, not a browser-level sandbox. Using --user-data-dir for isolation is the strongest mitigation.
• The script runs Runtime.evaluate with arbitrary JavaScript on QQ Music pages. This is equivalent to using the browser's DevTools console on that page.
• This is a community automation tool for a music player, not a security-critical application. Use common sense: don't run it on a machine you don't trust.

What it supports

• Cross-platform: Windows, macOS, Linux
• Cross-browser: Chrome, Chromium, Edge, Brave, Arc, or any browser exposing a DevTools/CDP endpoint
• Transport: play, pause, toggle, next, previous
• Search & play: songs, artists, albums
• Liked songs: play all, play random, like/unlike current track
• Playlists: list created playlists, create new playlists, add current song to a playlist, play a playlist by ID
• Mode control: list loop, single loop, shuffle, sequential
• Status: current track, artist, time, play state
• Screenshot capture

Requirements

• Node.js 18+ (uses built-in fetch and WebSocket)
• A Chromium-based browser with remote debugging enabled (see setup below)
• A QQ Music account logged in at y.qq.com (needed for liked songs, playlists, and like/unlike)

Setup guide (for Agents)

This skill connects to a browser via CDP. The Agent needs to:

1. Discover the CDP port
2. Cache it for subsequent calls
3. Ensure QQ Music is open and logged in

Step 1: Discover and cache the CDP port

Run the built-in browser status tool to get the current cdpPort, then write it to .cdp-port:

browser status → read cdpPort from response (e.g. 19011)
Write the port number to: <skill-directory>/.cdp-port

The .cdp-port file should contain only the port number, nothing else. Example content: 19011

Step 2: Verify the connection

node qq-music-ctl.js doctor

Check that status is "ready". If status is "connected_no_qq_music_tabs", open QQ Music first via node qq-music-ctl.js init. If status is "no_endpoint", the cached port may be stale — go back to Step 1.

Step 3: Ensure QQ Music is open and logged in

The user must have logged in to y.qq.com in the browser at least once. If there are no QQ Music tabs:

node qq-music-ctl.js init

This opens https://y.qq.com/ in a new tab. The user may need to log in manually the first time.

Note: This skill does NOT require any OpenClaw SSRF policy changes. It connects to CDP directly, not through OpenClaw's browser tool.

Connection failure recovery

If any command fails with "No DevTools endpoint found":

1. Re-run browser status to get the current cdpPort
2. Overwrite .cdp-port with the new port number
3. Retry the command

Controller script

All actions go through the bundled script:

node qq-music-ctl.js <action> [args...]

All output is JSON on stdout. Exit code 0 = success, 1 = error.

CDP port discovery

The script resolves the CDP port from:

1. .cdp-port file — a single-line file in the same directory as qq-music-ctl.js, containing just the port number (e.g. 19011).
2. Fallback 9222 — the Chrome documentation default.

All connections are restricted to 127.0.0.1. Remote endpoints are not supported.

For OpenClaw Agents: Run browser status (built-in tool) → read cdpPort from the response → write it to .cdp-port. The script will then use it automatically on every subsequent call. If a command fails with "No DevTools endpoint found", re-run browser status, update .cdp-port, and retry.

Action reference

Playback control

Search & play

Liked songs

Playlists

Play mode

Utility

How it works

1. Endpoint discovery: The script reads the CDP port from .cdp-port (or falls back to 9222), then probes 127.0.0.1:<port> for a DevTools HTTP endpoint (/json/version + /json/list).
2. Tab selection: Player-tab (/player URL) is preferred for transport controls (play/pause/next/prev/status). A separate browse-tab is used for search, navigation, and playlist operations.
3. DOM automation: All interactions use Runtime.evaluate over CDP to run JavaScript in the page context. No Puppeteer or Playwright dependency.
4. No external dependencies: The script is a single file using only Node.js built-ins (fs, path, WebSocket, fetch). No npm install needed.
5. Domain re-check: Before every Runtime.evaluate call, the script verifies the page's location.hostname is still on y.qq.com. If the page has navigated away, the call is rejected with an error.

Selection rules

• Prefer the player tab for transport controls.
• Prefer the browse tab for search and playlist discovery.
• If there is no QQ Music tab, init opens a blank tab and navigates to https://y.qq.com/.
• For song search, the first exact or containing title match wins; otherwise the first visible result is played.
• For liked songs, random play picks from the currently visible page (~10 songs; the web version does not expose all liked songs without scrolling).
• For add-to-playlist, if a newly created playlist is not yet visible in the player's menu, the player page is automatically reloaded to refresh the cache and retry.
• like and unlike are idempotent and report the current state.
• create-playlist accepts names up to 20 characters (QQ Music web limit).

Limitations

• The QQ Music web version shows at most ~10 liked songs per page. play-liked uses the "播放全部" button which queues all liked songs in the player, but play-liked-random can only pick from the visible ~10.
• System audio volume control is out of scope (OS-level, not browser-controlled).
• Some features (like VIP-only songs) depend on the user's QQ Music subscription.
• The skill does not handle QQ Music login; the user must log in manually first.

Troubleshooting

• "No DevTools endpoint found": The cached port in .cdp-port may be stale, or no browser is running with remote debugging. Re-run browser status, update .cdp-port, and retry. Run node qq-music-ctl.js doctor for detailed diagnostics.
• Port changed after browser restart: Delete .cdp-port, re-query via browser status, and write the new port.
• "Player not found": Play a song first (via search or play-liked) to make the player tab appear.
• Timeouts: Increase QQ_MUSIC_PAGE_WAIT_MS for slow connections, or QQ_MUSIC_PROBE_TIMEOUT_MS for slow endpoint discovery.
• "CDP connection closed": The page may have navigated or crashed. Retry the command.

Notes

• The skill does not assume a specific browser brand or OS.
• The skill does not hardcode any personal paths, usernames, tokens, or port numbers.
• The .cdp-port file is a local cache and should be added to .gitignore. It is not part of the published skill.
• If the browser exposes multiple DevTools endpoints, the controller probes the configured port and prefers the one with QQ Music tabs.

Disclaimer

This is a community-maintained tool for personal learning and research. It automates the QQ Music web UI through a user's own browser — equivalent to manual DevTools console usage. It is not an official QQ Music/Tencent plugin.

It does not reverse-engineer server APIs, extract music files, or bypass payment restrictions.

Users are responsible for complying with QQ Music's Terms of Service. If you receive a takedown notice from the rights holder, stop using this skill immediately.

Open-source, non-commercial, and provided as-is with no warranty.