• If you have Ajazz — download from links with ajazz in the URL
• If you have Mirabox — download Stream Dock (links without ajazz)
• Stream Dock from Mirabox technically works with Ajazz too:
  • On Windows — detects the device normally
  • On macOS — sees the device but doesn't connect properly

This happens because Ajazz AKP153 is hardware-wise a clone of Mirabox StreamDock 293S, and the system sees it under that name.

Place the com.judd1.yandex_music.sdPlugin folder in the plugins directory.

Press Win + R, paste this path and press Enter:

%AppData%\HotSpot\StreamDock\plugins

Place the com.judd1.yandex_music.sdPlugin folder in the plugins directory.

In Finder press Cmd + Shift + G and paste:

~/Library/Application Support/HotSpot/StreamDock/plugins

⚠️ Important: Since the plugin is not signed with an Apple Developer ID, macOS puts it in quarantine. After copying, run this command in Terminal:

xattr -cr ~/Library/Application\ Support/HotSpot/StreamDock/plugins/com.judd1.yandex_music.sdPlugin

Without this, the plugin fail to start and show "App is damaged" error.

— create a special shortcut

1. Find Yandex Music in the Start menu

2. Right-click → Open file location

3. Right-click on the file → Create shortcut

4. Open shortcut properties (right-click → Properties)

5. In the Target field, add at the very end (after the closing quote, with a space):

   --remote-debugging-port=9222
   

   It should look something like:

   "C:\Users\...\Yandex Music.exe" --remote-debugging-port=9222
   

6. Click OK and pin this shortcut wherever convenient

From now on, launch music only through this shortcut. Regular launch from Start menu won't work — this is important.

— create a wrapper app

You could open Terminal every time and enter the command, but that gets old fast. Better to create a launcher app once.

1. Open Script Editor — find it via Spotlight
2. Paste:

do shell script "open -a '/Applications/Yandex Music.app' --args --remote-debugging-port=9222"

If your app is named differently (e.g., "Яндекс Музыка.app"), adjust the path.

1. File → Export...
2. Name: Yandex Music Debug (or whatever you prefer)
3. Where: Applications
4. Format: Application
5. Uncheck all checkboxes
6. Save

Now a new launcher will appear in the Applications folder. Launch music through it.

The new app will have a default script icon. To restore the original Yandex Music logo:

1. Find the original Yandex Music.app in Applications
2. Cmd + I → click on the icon in the top-left corner of the window → Cmd + C
3. Find your Yandex Music Debug.app
4. Cmd + I → click on the icon → Cmd + V

Done, now the launcher looks like the original and works as intended.

This is a separate FastAPI server that acts as a proxy between the plugin and the Ynison protocol. The plugin communicates with it via WebSocket and HTTP, and the server maintains the connection with Yandex.

┌─────────────────────┐      WebSocket       ┌───────────────────────┐
│   Stream Deck       │ ◀──────────────────▶ │   api_for_plugin      │
│   Plugin            │      /ws             │   (FastAPI)           │
└─────────────────────┘                      └───────────────────────┘
                                                       │
                                    ┌──────────────────┴──────────────────┐
                                    │                                     │
                                    ▼                                     ▼
                       ┌────────────────────────┐          ┌──────────────────────────┐
                       │   Ynison WebSocket     │          │   Yandex Music REST API  │
                       │   wss://ynison.music.  │          │   api.music.yandex.net   │
                       │   yandex.ru            │          │   (likes, metadata)      │
                       └────────────────────────┘          └──────────────────────────┘

WebSocket /ws

• Header Authorization: <token>
• Automatically starts Ynison session for this token on connection
• Receives real-time player state updates (JSON)

POST /control/{action}

• Actions: play_pause, next, prev, like, dislike
• Header Authorization: Bearer <token> or Authorization: <token>
• Returns {"status": "ok"}

GET /check_token

• Validates token
• Returns {"valid": true} or {"valid": false}

• Multi-user mode — one server for multiple users, lazy sessions
• Metadata enrichment — Ynison only provides ID, server fetches covers and names via REST
• Like synchronization — liked/disliked lists are loaded on session start
• Fault tolerance — auto-reconnect, timeouts, graceful shutdown
• Pydantic models — entire protocol is typed and validated

cd api_for_plugin
pip install -r requirements.txt
python main.py

Server will start on http://0.0.0.0:8000

Local mode uses Chrome DevTools Protocol to control the Yandex Music client directly, without third-party servers.

┌─────────────────────┐                     ┌───────────────────────────────────────┐
│                     │                     │       Yandex Music (Electron)         │
│    Stream Deck      │                     │                                       │
│      Plugin         │                     │   ┌───────────────────────────────┐   │
│     (Python)        │      WebSocket      │   │       injected_api.js         │   │
│                     │ ◀─────────────────▶ │   │   (injected script)           │   │
│                     │  ws://localhost:    │   │                               │   │
│  CDPMediaController │  .../devtools/page  │   │      window.sdNotify() ──────▶│───│──▶ Runtime.bindingCalled
│                     │                     │   │      (callback)               │   │
└─────────────────────┘                     │   └───────────────────────────────┘   │
         │                                  │                                       │
         │ HTTP GET                         │   CDP Debug Port :9222                │
         └─────────────────────────────────▶│   (--remote-debugging-port)           │
           /json (get WS URL)               └───────────────────────────────────────┘

1. Connection:

   • Plugin requests http://localhost:9222/json to get WebSocket URL
   • Opens WebSocket connection to the page via CDP
   • Calls Runtime.addBinding("sdNotify") to register callback

2. Script injection:

   • Plugin injects injected_api.js via Runtime.evaluate
   • Script creates window._PyYMController object
   • Script starts observing via MutationObserver

3. Receiving updates (event-driven):

   • When player state changes, script calls window.sdNotify(JSON)
   • CDP delivers this via Runtime.bindingCalled event
   • Plugin parses payload and updates UI

4. Sending commands:

   • Plugin calls Runtime.evaluate with controller method
   • For example: _PyYMController.togglePlayPause()
   • Script finds the right button and emulates click

• data-test-id selectors — stable between Yandex Music versions
• Fallback chains — if main selector not found, try alternatives
• Delta updates — only changed fields are transmitted, not entire state
• Optimistic UI — buttons update immediately on press
• Auto-reconnect — plugin reconnects automatically on connection loss