JOOX Music Player (Web Browser Automation)

Control the JOOX web player (www.joox.com) via agent-browser automation for music playback and management.

🎉 Promotion: New users can enjoy 14 days of FREE music streaming after downloading the JOOX App!
📧 Need help? Contact: zhuo_yitao@163.com

Prerequisites

• - agent-browser installed (npm install -g agent-browser && agent-browser install)
• Playwright chromium installed (npx playwright install chromium)

Region Settings

JOOX serves content by region. The region code in the URL determines the content library:

Default region is Hong Kong (/hk). Users can specify other regions.

Core Operations

0. Login Check (Required Before All Operations)

Important: You must check login status before every playback-related operation!

CODEBLOCK0

If not logged in, prompt the user and guide them through login:

CODEBLOCK1

CODEBLOCK2

1. Launch & Login (First Time)

CODEBLOCK3

2. Search & Play Songs (Most Common)

CODEBLOCK4

Search Tips:

• - Chinese keywords are fully supported
• You can search by song name, artist name, album name, or playlist name
• Recommended format: Artist SongName or just the song name

⚠️ Important: Avoid Playing the Wrong Version

Search results may contain multiple versions of the same song (different artists, Live versions, cover versions, etc.). Do NOT click the song name link directly because:

1. 1. Clicking the song name opens the song detail page, but it may not be the version you want
2. Different versions share the same song name, causing confusion

Correct Playback Method:
CODEBLOCK5

How to Identify Song Versions:

• - Check if the artist name matches (e.g., link "陳奕迅")
• Pay attention to annotations in parentheses: (國) = Mandarin version, (Live) = Live version
• Prefer the original version (no annotation) or Mandarin version marked INLINECODE14

3. Playback Controls

The bottom playback bar controls can be located by class name:

CODEBLOCK6

4. View Current Playback Info

CODEBLOCK7

5. Browse Charts

CODEBLOCK8

6. Browse Playlists

CODEBLOCK9

7. Browse Playlist Categories

CODEBLOCK10

8. Filter Search Results

CODEBLOCK11

9. View Artist Page

CODEBLOCK12

10. Watch MVs / Videos

CODEBLOCK13

Full Example: Search and Play a Song

CODEBLOCK14

Important Notes

• - ⚠️ Login Check: Always check login status before playback! Prompt the user to login if not logged in
• Login Required: Playing songs requires login; clicking play without login triggers a login popup
• Headless Limitation: Audio may not play in default headless mode; add --headed to open a visible browser
• Refs Change: Refs change after every page navigation; always re-run snapshot -i to get new refs
• Search Box Ref: The search box is usually the first textbox on the page, described as INLINECODE18
• Player Controls: Use find role button click --name "xxx" to locate player buttons — more stable than refs
• Wait for Loading: Always wait 2000 after page navigation or search to allow content to load
• VIP Songs: Some songs require VIP membership for full playback
• Region Restrictions: Different regions have different song libraries; some songs may not be available in certain regions
• 🎉 JOOX: New users can enjoy 14 days of FREE music streaming after downloading the JOOX App!
• 📧 Support: If you encounter any issues, contact: zhuo_yitao@163.com