Files
musyx/README.md
T
yuriy.pandClaude Opus 5.5 f80de805c2 feat: Linux release packaging
Tarball, .deb and AppImage from tool/bundle-linux.sh, and an Arch PKGBUILD.
The window carries the dev.musyx.Musyx app id so desktops match it to the
installed desktop entry and icons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 12:27:50 +06:00

130 lines
5.6 KiB
Markdown

# Musyx
A desktop player for Yandex Music, written in Rust with [iced](https://iced.rs).
Musyx is an unofficial client. It talks to the same undocumented API the official apps use,
and it isn't affiliated with or endorsed by Yandex.
## Layout
- `crates/ym-api`: the Yandex Music API client, with no UI dependencies.
- `crates/musyx`: the iced app (screens, widgets, player, theme).
- `design/mockup.html`: the approved design. `DESIGN.md` records its tokens.
## Run
```sh
cargo run -p musyx
```
### Sign-in
Musyx signs in with Yandex's device flow. It shows a code, you confirm it at the page Yandex
names (or scan the QR code), and the app picks up the token on its own. You can also paste an
existing OAuth token. The token is kept in the system keychain (service `musyx`, account
`yandex-music`) and refreshed when it is within a week of expiring. Signing out deletes it.
Sign-in uses the public OAuth client id of the official Android app (through
[`yamuse`](https://crates.io/crates/yamuse)), because the music API doesn't accept
third-party apps. On macOS an unsigned dev build may ask for keychain access again after
each rebuild, because the keychain ties access to the binary's signature.
## Install on macOS
```sh
tool/bundle-macos.sh --install
```
This builds a release `Musyx.app` into `target/release/bundle/`, signed with the
`Developer ID Application` certificate of team `H33L24BGUH` and the hardened runtime. With
`--install`, it also copies the app to `/Applications`. The icon comes from
`crates/musyx/assets/icon/musyx.png`, which `tool/make_icon.py` draws. Set
`MUSYX_SIGN_IDENTITY` to sign with another identity, or to `-` for an ad-hoc signature
(each ad-hoc build is a new code identity, so macOS asks again for keychain access).
## Install on Linux
```sh
tool/bundle-linux.sh # tarball, .deb and AppImage into target/release/bundle/
tool/bundle-linux.sh tar deb # only the formats named
tool/bundle-linux.sh --install # install into ~/.local (PREFIX picks another prefix)
```
On Arch, `makepkg -si` in `packaging/arch` builds and installs the committed `HEAD`.
Building needs `pkg-config` and the ALSA and D-Bus development files (`alsa-lib` and `dbus`
on Arch, `libasound2-dev` and `libdbus-1-dev` on Debian/Ubuntu). The AppImage also needs
[`appimagetool`](https://github.com/AppImage/appimagetool/releases) on `PATH` (or
`APPIMAGETOOL`). A binary runs only on a glibc at least as new as the one it was built
against, so build release packages on the oldest distro you want to support.
The desktop entry, metainfo and icons are installed as `dev.musyx.Musyx`, which is also the
window's Wayland app id. The token goes to the Secret Service (GNOME Keyring, KWallet,
KeePassXC), and media keys and the desktop's player widget work through MPRIS. The menu bar
mini player is macOS-only.
## Settings
Settings (streaming quality, appearance, language, volume) are kept in
`~/Library/Application Support/Musyx/settings.json` on macOS and
`~/.config/musyx/settings.json` on Linux. Covers are cached under
`~/Library/Caches/Musyx/covers` (`~/.cache/musyx/covers` on Linux) and can be cleared from
Settings.
Streaming quality **Lossless** asks Yandex for FLAC (through the signed `/get-file-info`
endpoint, decrypting its AES-CTR stream in memory). Yandex decides what to grant by
subscription, region and track. When there's no FLAC, it answers with the best lossy file
it allows, and Musyx plays that. The badge in the player bar shows what was actually served,
and turns accent-coloured for FLAC.
The interface is in English and Russian. **Language** in Settings follows the system's first
preferred language by default, and can be set to either. Yandex's own titles (genres, Home
blocks, station names) switch with it. Strings are written in English in the code as
`tr("…")` or `trf("… {} …", &[…])`. The Russian text lives in
`crates/musyx/src/i18n/ru.rs`, and `cargo test` fails for any string that has no entry
there. `MUSYX_SNAPSHOT_LANG=ru` renders a snapshot in Russian.
## Check
```sh
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
Snapshot mode renders one screen to a PNG through iced's own screenshot, so it needs no
screen-recording permission:
```sh
MUSYX_SNAPSHOT=design/shots/home.png MUSYX_SNAPSHOT_ROUTE=home MUSYX_SNAPSHOT_THEME=dark \
cargo run -p musyx --features snapshot
```
`MUSYX_SNAPSHOT_ROUTE` takes home, wave, search, collection, podcasts, settings, signin or
`artist:<id>` (live runs only). Every route except signin renders with a sample signed-in
account, so no network or keychain is needed.
`MUSYX_SNAPSHOT_DRAWER` takes queue or lyrics. `MUSYX_SNAPSHOT_THEME` takes light or dark.
`MUSYX_SNAPSHOT_LIVE=1` signs in with the account stored in the keychain instead of using sample
data. Set `MUSYX_SNAPSHOT_DELAY` (ms) to wait longer for slow pages.
`cargo run -p musyx --example api_probe` calls the discovery endpoints with the stored account
(read-only) and prints what came back.
### Tracing
`MUSYX_TRACE=1 cargo run -p musyx` logs each user action (not playback ticks or cover loads)
to stderr, followed by what's playing and the next three tracks.
### Audio
`cargo run -p musyx --example audio_probe` lists the output devices and checks that each one
opens. Use it when the player bar says no sound output was found.
`cargo run -p musyx --example stream_probe -- "artist title"` asks for the lossless stream
of the first search hit with the stored account (read-only). It downloads and decrypts the
file, and prints the codec Yandex granted plus the decoded sample rate.
## Licences
Musyx is MIT. Onest and Unbounded are OFL (`crates/musyx/assets/fonts`), and Lucide icons
are ISC (`crates/musyx/assets/icons/LICENSE.txt`).