Skip to content

About

A DJ for your collection music: endless beat-matched mix of tracks that flow into one another, with queue, mood and genre controls.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

EndlessWave

A tray player for the endless DJ radio:
tracks from Yandex Music or your own folder, beat-matched and blended into one continuous mix.

The player, light mode   The player, dark mode

What is it

EndlessWave takes tracks from a Yandex Music station (or from a folder of music files), matches their tempo, swaps the bass and mids at the joins and streams the result as one endless mix with no gaps. Tracks are levelled towards −16 LUFS with at most 12 dB of boost; sample peaks stay at or below −1 dBFS, so dynamic recordings may remain quieter. The mix keeps the same sample-peak ceiling, with headroom for encoding. It plays the mix and shows what plays, what comes next and how the blends go:

  • it plays the mix (MP3 or lossless FLAC) through the system's audio output;
  • it lives in the tray and answers to the media keys and the system's Now Playing (Control Center on macOS, MPRIS on Linux);
  • it runs on macOS (Apple Silicon) and Linux (x86_64), in light or dark mode as the system has it.

The radio is inside the app, and the packages hold ffmpeg: nothing else has to be installed, no ffmpeg.

Features

A mix without gaps Beat-matched blends: bass swap, three-band EQ blend, filter sweeps, effects. Keys are chosen to sound harmonic
The queue under control Drag the tracks to reorder them, take out the ones you do not want, play any of them at once
Mood, genres, language Pick the mood (calm, fun...), the genres to play and the genres never to play, the language of the music
Sources Yandex Music, VK Music and/or a local folder (mp3, flac, m4a, ogg, opus, wav...). Any of them can play at once
MP3 or FLAC A switch for the stream: MP3 at 320 kbit/s, or lossless FLAC (16 bit)
Spectrum The real spectrum of the mix, in time with the sound
Native audio The app plays the stream itself, through the system's audio output (CoreAudio on macOS, PipeWire on Linux, ALSA where there is none)
The system Tray, media keys, Now Playing with the cover, keyboard shortcuts, hide to the tray
Statistics How many blends there were and how well tempo and key matched

Mood, language and genres

Install

Download a package from the Releases page.

macOS (Apple Silicon): open the .dmg and drag the app to Applications. The build is not signed, so macOS asks to confirm the first start: System Settings → Privacy & Security → "Open Anyway" (or right-click the app → "Open").

Fedora (RPM):

sudo dnf install ./endlesswave-*.x86_64.rpm

Debian / Ubuntu (DEB):

sudo apt install ./endlesswave_*_amd64.deb

The sound is played by the app itself through PipeWire (ALSA is the fall back where there is no PipeWire), so nothing else is needed. For the tray icon, GNOME needs the AppIndicator extension.

First start and setup

Open the app: the radio service starts by itself (port 18000, on 127.0.0.1 only).

Keyboard: ⌘R rebuilds the queue, ⌘⇧R (or holding the rebuild button for 3 s) clears it and loads it anew, ⌘D likes or unlikes the playing track; ⌘/ lists all the shortcuts.

Equalizer

Click the level meter next to the track (or press ⌘E) to open the equalizer in its own window: ten bands (32 Hz to 16 kHz, ±12 dB) to drag, move with the arrow keys, or pick from the presets. It shapes the sound of the app's own player; other listeners of the stream (a browser, VLC) hear the radio as it is.

The player's display shows what plays the set: a badge under the track (Free, Mood arc or the part of the day, with a clock when it follows the clock) with the tempo and the mood the plan is aiming at now, and dots for its stages (the one that is on is wider). Click it to open the Mix tab.

Mix: what plays the set

The Mix tab starts with one choice, and only its settings are shown: Free (the radio picks the energy by itself; narrow it with the moods, language and genres), Mood arc (the set follows your arc of moods) or Parts of the day (morning, day, evening, below). Language and genres are always at the bottom.

Mixing by phrases

Mix → Transitions → Mix by phrases aligns complete 8-, 16- or 32-bar phrases. Section edges restart the phrase grid. The automatic player favours an outgoing outro or breakdown and brings the incoming intro or breakdown to its build-up or drop at the end of the blend. Transitions use the final quarter of the outgoing track; its remaining tail may be omitted after the transition. Phrase boundaries are estimates from beats and energy, so irregular arrangements can still need the original beat-matched fallback. Unknown tempo, incompatible phrase lengths or insufficient space also use that fallback.

The switch affects newly prepared tracks; already prepared decks keep their plan. The Next button continues to use the original early-transition algorithm.

Morning, day, evening

In Mix, Morning · Day · Evening plays the set along a plan of the tempo; each cycle has its own, which you can change:

  • Morning starts quiet, about 60 BPM, and goes up to 120 BPM, stage by stage (a point for each stage; drag it up or down).
  • Day plays the mood arc (below) within a range of BPM (by default 95–135).
  • Evening plays quiet music only (calm, sad) and slows down from 100–120 BPM to 40–60 BPM.

For the morning and the evening you set the points, how many tracks each stage lasts (the same for all) and how far from the line a track may be (the band around it). The plan goes on to its last stage and stays there. The radio picks the tracks that are nearest to the line (a tempo found at half or double speed counts, a little less), and asks the services for music of the mood that goes with it.

Mood arc

In Mix, the Mood arc is a line of points: each point is a stage of the set, and its height is the mood, from sad (bottom) to lively (top). Drag a point up or down to change its mood, add or remove stages with + and −, and set how long each stage lasts (the same for all, in tracks). Switch it on and the radio goes through the stages one after the other and starts over after the last. It steers the stations that follow a mood (Yandex Music, VK) and favours tracks of the stage's mood in the queue, whatever the source. Off, the radio follows its built-in arc.

Wave or liked tracks

In Sources, under each signed-in service, the row Tracks chooses where its tracks come from: the wave (My wave of Yandex Music, the wave of VK) or your own liked tracks, in a random order. The choice is kept per service; when it changes, the tracks of that service waiting in the queue make way for the new ones.

Signing in to VK Music

In Sources turn on VK Music and press sign in with VK: a window with the VK site opens, you sign in there as in a browser (password, code, QR), and the window closes by itself. The app takes the cookies of the session from it, swaps them for an access token, and asks for a new token when it runs out. The window keeps nothing; the cookies are kept in the database of the app (the file is readable by you only). You can also paste an access token instead. The radio plays the VK wave (recommendations) by default, or your own music with the station favorites. The heart in the player adds a track to your VK music or takes it out. This uses the unofficial API of the VK site, so it may stop working when VK changes it.

Signing in to Yandex Music

If you have not signed in yet, a card "Sign in to Yandex Music" shows at the top:

  1. Press Copy code (the code goes to the clipboard) and Open: the Yandex page opens.
  2. Paste the code and confirm the sign-in.

The token is kept in the database of the radio, ~/.cache/endlesswave.db (mode 0600), so you sign in once.

Music from a folder

Open Sources → turn Local folder on → Choose… → pick the folder (or just drag the folder from Finder onto the window). Subfolders are read too, and the tags (title, artist, genre) come from the files. Yandex Music can stay on or be turned off: the tracks of both sources go into one pool.

Local tracks have no covers and no moods: the mood is judged by the sound. The language setting works for Yandex Music only.

Mood, language, genres

The Mix tab:

  • Mood: pick one or several. None picked means any;
  • Language: the language of the music (Yandex Music);
  • Genres: the pick mode chooses the genres to play, block the ones never to play. The list of genres grows as tracks are played;

A choice takes effect at once: the queue is built again for the new settings. You can rebuild it by hand with the ⟳ button (⌘R). The settings are remembered and come back after a restart.

DJ console

Open DJ Console from the app menu. Deck A takes the track you are hearing, at its current position; deck B takes the next track and waits paused. The radio keeps playing while the decks load, then the same audio output blends into the console. Closing the console continues the audible deck in the automatic mix, without restarting the track or reconnecting the audio device. If both decks are playing, the crossfader and channel faders decide which one continues. An unheard track on the other deck stays next; tracks already heard in the console are not put back in the queue. Paused playback stays paused.

Settings

The Settings sheet is the gear in the top bar (⌘ ,). The sound is played by the app's own player (the system's audio output); if it cannot start (no audio device, for instance), the app says so.

On macOS, Appearance can hide the Dock icon and the app's menu: the player then lives in the menu bar only, and the window opens from the tray icon.

Reset starts the radio afresh: it clears the queue, the settings of the mix, the sources and the app, and the history of listening (with the statistics). The sign-in and the cache of the analysis of the tracks stay.

Updates: the app looks for a new version of itself twice a day and shows a card with a Download button (it opens the page of the release). Check now (or Check for Updates… in the app menu on macOS) asks at once.

Using it

Buttons ▶/⏸ play and pause · ■ stop · ⏭ next track · ⟳ rebuild the queue · MP3/FLAC the stream format · the volume slider
Next track The blend starts on the next bar line and is as smooth as any other. The button stays pressed until the new track is heard
The queue Drag a track with the mouse to move it. Hover a row: ▶ plays it now (or double-click), ✕ takes it out of the queue. The track being blended in just now is fixed
Tray The menu: what plays, pause, next, show the window, quit. Closing the window only hides it to the tray; Quit stops the app and the service
System Media keys and Now Playing (Control Center on macOS, MPRIS and playerctl on Linux)

Keyboard shortcuts

On macOS the shortcuts are in the menu bar (Controls and View), so you can find them there. On Linux, Ctrl takes the place of ⌘. The whole list is shown by ⌘ /.

Key Action
Space Play / pause
⌘ . Stop
⌘ → Next track
⌘ R Rebuild the queue
⌘ L MP3 ⇄ FLAC
⌘ ↑ / ↓ Volume
⌘ 1–4 Tabs: Playlist, Mix, Sources, Stats
⌘ , Settings
⌘ / The list of shortcuts

How it works

┌──────────────────────────┐   HTTP API, SSE, /stream    ┌──────────────────────────┐
│  EndlessWave             │ ◄─────────────────────────► │  the radio (radio-core)  │
│  Tauri + Vue 3           │      127.0.0.1:18000        │  Rust, on its own thread │
│  window, tray, sound     │                             │  ├─ MP3, FLAC, Ogg built │
└──────────────────────────┘                             │  └─ Yandex Music / folder│
                                                         └──────────────────────────┘

The app reads the stream itself, decodes it (MP3, FLAC) and plays it through the system's audio output; the window only controls it. Everything else (the queue, the moods, the spectrum) comes from the API of the radio. The radio runs inside the app (crates/radio-core); if something already answers on port 18000, the app connects to it.

Files of the radio (versions before 0.2 kept them as ~/.config/yamusic-radio.json, ~/.cache/yamusic-radio.db and so on; the first start moves the database to the new name, takes the token file into it and removes the old files, the loaded tracks and the log):

What Where
The Yandex Music token and its settings, the cache of the analysis, the settings of the radio ~/.cache/endlesswave.db (mode 0600)
The loaded tracks that wait for their turn ~/.cache/endlesswave-tracks/
The log (only with ENDLESSWAVE_LOG=1) ~/.cache/endlesswave.log

Environment: ENDLESSWAVE_PORT (the port, 18000 by default), ENDLESSWAVE_ARGS (any more flags of the radio, e.g. --no-keep-tracks; endlesswave-radio --help in crates/radio-core lists them), ENDLESSWAVE_LOG=1 (write the log to a file; it is not written otherwise), ENDLESSWAVE_DEBUG=1 (a detailed log, to the file too).

Troubleshooting

  • No sound, the queue is empty. The service is waiting for tracks. The log is not written by default. Start the app with the log on, then read it: on macOS open -n --env ENDLESSWAVE_LOG=1 -a "EndlessWave", on Linux ENDLESSWAVE_LOG=1 endlesswave, and tail -f ~/.cache/endlesswave.log. Unknown HTTPError in it means Yandex Music does not answer or limits the requests.
  • No tray icon on Linux. AppIndicator is needed (in GNOME, the AppIndicator and KStatusNotifierItem Support extension). The tray menu still works, a click on the icon does not open the window.
  • No sound on Linux. The native player needs a working audio output (PipeWire, or ALSA).

Development

You need Node.js 22+ and Rust (stable). The radio is in crates/radio-core (see docs/rust-port.md); for the keys and the loudness the way the original radio found them build with --features essentia after crates/radio-core/tools/fetch-vendor.sh.

npm install
npm run tauri dev      # the window, with hot reload

Type check: npx vue-tsc --noEmit. The radio's tests: cargo test in crates/radio-core. Signal-level regressions are in mix_quality and deck_loudness: peak ceilings, smooth gain, stereo linking, LUFS matching and the joins after tempo changes. An opt-in check renders five adjacent transitions and one compatible phrase transition from six tracks in the local download cache (or the folder named by RADIO_QUALITY_TRACKS), without starting a server. The sample must contain a compatible phrase pair:

cargo test --manifest-path crates/radio-core/Cargo.toml --test mix_quality real_tracks -- --ignored --nocapture

The app icon is drawn in assets/icon.svg (python3 assets/make-icon.py, then python3 assets/render-icon.py for assets/icon.png, then npx tauri icon assets/icon.png makes all the sizes); the menu bar icon of macOS is src-tauri/icons/tray.png (assets/tray.svg).

Layout: src/ is the interface (Vue 3, Vuetify), src-tauri/ the shell (starts the radio, the tray, the window), crates/radio-core/ the radio, scripts/ builds ffmpeg and the packages.

Build

The packages hold a static LGPL ffmpeg (it decodes what the radio can not: HE-AAC, Opus); the radio is built into the app.

Platform Result Command
macOS arm64 .app / .dmg npm run bundle on a Mac
Linux x86_64 .rpm, .deb npm run bundle:linux (in a podman container)

Limits

  • The macOS build is not signed or notarized (that needs a Developer ID certificate).
  • Apple Silicon only on macOS, x86_64 only on Linux.
  • This is a radio: there is no previous track and no seeking.
  • On Linux the window frame of the system is drawn together with the app's own top bar.

License

The player is released under the GNU Affero General Public License, version 3 or later. The source is this repository; the radio was ported from the author's Python radio, whose answers are kept as test data in crates/radio-core/tests/golden. Versions up to 0.1.0 were released under the MIT License.

Third-party parts

The full texts of all of them (the Rust crates and the JavaScript packages too) are in THIRD-PARTY-LICENSES next to the app in the package; scripts/third-party.sh makes it.

  • ffmpeg 9.0.2 (LGPL-2.1+) and LAME 4.0 (LGPL): built without any GPL parts; the license text is next to the binary in the package.
  • Essentia (AGPL-3.0): built into the app from source (crates/radio-core/vendor, fetched by tools/fetch-vendor.sh), finds the keys and the loudness of the tracks. The packages that hold it can only be passed on under the AGPL-3.0, which is why the player has this license.
  • LAME (LGPL), flacenc (Apache-2.0), symphonia (MPL-2.0), rubato (MIT): the MP3 and FLAC encoders and the decoders of the radio.

About

A DJ for your collection music: endless beat-matched mix of tracks that flow into one another, with queue, mood and genre controls.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages