Introduction

Listen is a native desktop music player for Linux and Windows. It plays music from your own server, from YouTube Music, from folders on your computer and from internet radio, all in one queue. This page explains what it is, what it can do and how this guide is organised.

What Listen is

Listen is written in Rust. It has no web view and no Electron runtime: it is one small program that starts quickly and keeps memory use low. The interface is drawn with iced and audio is played by mpv.

Its layout follows Feishin closely, so if you have used Feishin you will find the home feed, the album, artist and genre pages, the command palette, the full-screen player and the settings where you expect them. Listen is a separate program written from scratch, and it can import your Feishin settings (see Importing from Feishin).

Where the music comes from

You can add several servers and switch between them, and one queue can hold songs from different sources. See Connecting your music.

What it adds to a player

• Gapless playback with ReplayGain, an equalizer, a compressor, speed and pitch control and a choice of output device.
• Beat-matched DJ transitions between songs (DJ transitions) and an optional AI DJ that picks sets and talks between them (AI DJ).
• Synced lyrics, a visualizer, music videos for YouTube Music songs and DLNA casting to speakers and TVs.
• Offline downloads from your own server, listening history with statistics, playlists and smart playlists.
• Media keys, global hotkeys, a tray icon, Discord status, a remote-control web page and a built-in MCP server.
• 32 built-in themes, custom themes and 17 interface languages.
• A built-in updater that installs new releases from the project’s public GitHub page.

What Listen does not do

• It does not provide any music. It plays what your servers, files and accounts give you access to.
• It sends no telemetry and has no account of its own. See Privacy and security.
• It does not download YouTube Music songs for offline use.

Note: Listen is an independent project. It is not affiliated with or endorsed by Google, YouTube, Navidrome, Jellyfin or Feishin.

How to read this guide

If you are new, read the Getting started chapters in order: Installation, First start, Connecting your music, and YouTube Music if you use it. The chapters under Using Listen and Playback describe everyday use. Reference lists every setting, MCP tool and command-line option, and Development is for people who want to build or change Listen.

If you want to look around before connecting anything, start the app with listen --demo (see Installation).

Installation

This page explains how to install Listen on Windows, Fedora and other Linux distributions, and how to try it without a server. Download all packages from the project’s Releases page on GitHub (the latest release is the one marked “Latest”).

Windows 10 and 11

1. Download Listen-Setup-<version>.exe and run it.
2. Windows SmartScreen may say the app is unrecognised, because the installer is not code-signed yet. Click More info, then Run anyway.
3. Follow the installer. You can tick an option to create a desktop icon, and the last page offers to start Listen.

The installer installs for your user only, into %LOCALAPPDATA%\Programs\Listen, and needs no administrator rights. A Start menu entry is always created.

Note: Some antivirus programs find it unusual that Listen can read a browser’s YouTube sign-in. Listen reads only the cookies of youtube.com and music.youtube.com, only when you choose a browser for YouTube Music, and sends them nowhere but YouTube. See YouTube Music.

Helper programs

Listen plays through three separate open-source programs:

The last step of the first-start wizard installs them for you with winget, Windows’ package manager. Listen opens a console window of its own that runs winget install for the programs that are missing. mpv asks for administrator rights once. When winget is done, press Check again; Listen uses the programs after a restart.

If you skipped the wizard or something is still missing, Listen shows a Helper programs dialog when it starts, with Install with winget, Check again and Later. You can also install the programs yourself:

winget install shinchiro.mpv yt-dlp.yt-dlp DenoLand.Deno

To update them, for example when YouTube Music songs stop playing, open Settings → Advanced → Updates → Helper programs and press Update. Show opens the dialog with the current state of each program.

Tip: If winget is missing, the console window points you to “App Installer” in the Microsoft Store.

Fedora

Install the RPM with dnf:

sudo dnf install ./listen-<version>-1.fc44.x86_64.rpm

Pick the file that matches your Fedora release (the fc44 part). The RPM pulls in mpv, PipeWire’s pw-record (for the visualizer) and the graphics libraries Listen needs. It recommends yt-dlp and Node.js for YouTube Music, plus a few optional packages (for example udisks2 for CD ripping and cifs-utils). If your setup skips recommended packages, install yt-dlp and nodejs (or Deno) yourself if you use YouTube Music.

The RPM installs the program under /usr, adds the menu entry and icon, and lets the built-in updater update it later (see Updates).

Other Linux distributions

Download listen-<version>-x86_64.tar.gz, unpack it and copy three files into your home folder:

tar xzf listen-<version>-x86_64.tar.gz
install -Dm755 listen-<version>-x86_64/listen ~/.local/bin/listen
install -Dm644 listen-<version>-x86_64/io.github.leks2205.Listen.desktop ~/.local/share/applications/io.github.leks2205.Listen.desktop
install -Dm644 listen-<version>-x86_64/io.github.leks2205.Listen.svg ~/.local/share/icons/hicolor/scalable/apps/io.github.leks2205.Listen.svg

Make sure ~/.local/bin is on your PATH. The archive also contains the licence files and the README.

Install these runtime dependencies with your package manager:

yt-dlp needs a JavaScript runtime to talk to YouTube. Listen finds Deno or Node in the usual places, including ~/.nvm and ~/.local/bin, even though desktop applications do not get your shell’s PATH.

A tarball install in ~/.local/bin can be updated by the built-in updater, which replaces the file in place (see Updates).

Try it without a server

To look around first, start Listen in demo mode:

listen --demo

Demo mode uses a small built-in library with placeholder artwork, so no server or account is needed. It does not save settings or credentials, and it does not check for updates. See Command line for the other options.

Building from source

If you prefer to build Listen yourself, see Building from source.

First start

The first time you start Listen, a short setup wizard offers the extras you may want. This page walks through its steps and what happens afterwards.

The wizard appears only on a fresh install: when no setup has been completed and no server is configured. Every step can be skipped and every choice can be changed later in Settings. The steps are listed on the left; click one to jump to it, or use Back and Next. Skip setup at the bottom left closes the wizard at any time.

1. Welcome

Choose the interface Language. The default, System default, follows your system language. The list has 17 languages; see Languages. The wizard switches language immediately.

2. Features

Tick what you want. Everything here is a normal setting that you can change later.

3. Analysis folder

DJ transitions need each song’s tempo, beats and key. Listen measures them once and keeps the results. Press Choose folder… to store them in a folder of your choice. If you pick a synced folder (Nextcloud, Syncthing and so on), your other computers reuse the results instead of measuring again.

Without a folder, results stay in Listen’s own data folder and YouTube Music songs are not analysed. Analyse YouTube Music songs is off by default and can only be switched on once a folder is chosen; Listen then fetches a temporary copy of each YouTube Music song it is about to mix and keeps only the measurements.

4. AI DJ

This step takes your Gemini API key for the AI DJ. You can skip it. The wizard shows the three steps to create a key (open Google AI Studio, click Create API key, copy the key that starts with AIza), a button Open Google AI Studio, a field for the key and Save key. After saving, tick Turn on the AI DJ.

The full walkthrough, including what is sent to Google, is in Creating a Gemini API key and AI DJ. In short: requests go from your computer straight to Google, and the key is kept in your system keyring. Outside the EU, UK and Switzerland, Google may use free-tier requests to improve its products.

5. Helper programs (Windows only)

On Windows the last step installs mpv, yt-dlp and Deno with winget. See Installation. On Linux the wizard has four steps and ends at the AI DJ.

Connect your music

On the last step the Next button reads Connect your music. It closes the wizard and opens the sign-in page, where you add your first source. Continue with Connecting your music.

If you cancel out of the wizard with Skip setup, the same sign-in page appears. The wizard is not shown again once it is finished, or once a server exists.

Connecting your music

This page explains how to add a Navidrome or OpenSubsonic server, a Jellyfin server and local folders, and how to manage several servers. YouTube Music has its own page: YouTube Music.

Open the sign-in page

On a fresh install the sign-in page appears after the first-start wizard. Later, open it with Add server in the sidebar’s server list, in the app menu, or in Settings → General → Servers.

The page has four tabs: Navidrome, Jellyfin, YouTube Music and Local. Below the form it lists Your servers, so a broken entry can be edited or removed from here too. If you already have a server, a Cancel button takes you back.

Passwords are stored in your system keyring (Secret Service on Linux, Credential Manager on Windows). If there is no keyring, they go in a credentials file in Listen’s config folder that only your user can read. You can choose with Settings → General → Servers → Password storage: System keyring or File only.

Navidrome and OpenSubsonic

Any server that speaks the OpenSubsonic (Subsonic) API works: Navidrome, Gonic, Airsonic and similar.

1. Choose the Navidrome tab.
2. Enter the Server URL, for example https://music.example.com, your Username and Password.
3. Press Connect.

Two switches adjust how Listen talks to the server:

Jellyfin

1. Choose the Jellyfin tab.
2. Enter the Server URL, for example https://jellyfin.example.com, plus Username and Password, and press Connect.

Only the server’s music libraries are used.

Discovery. When you open the sign-in page (on a fresh install, or with Add server), Listen looks for Jellyfin servers on your local network and lists them under Found on your network. Press Use to fill in the address. Press Scan again to search again. Servers you already added are not listed.

Quick Connect. Instead of typing a password, press Sign in with Quick Connect. Listen asks the server for a code. On a device where you are already signed in to Jellyfin, open Quick Connect and enter the code, or press Open the approval page. Listen waits for the approval and signs in. Cancel Quick Connect stops waiting.

Jellyfin has two extra switches:

Local folders

1. Choose the Local tab.
2. Type a path such as ~/Music, or press Browse… and pick the folder.
3. Press Connect.

Listen reads the tags and cover art of the files in the folder and its subfolders (MP3, FLAC, Ogg, Opus, M4A, WAV and more). Large folders take a moment to scan. You can add more than one folder; each becomes its own entry in the server list.

After you add files, press Rescan next to the folder in Settings → General → Servers.

Several servers side by side

Every source you add appears in the sidebar’s server list at the top, with its type underneath. Servers that are not connected yet show “not connected”.

• Switch: click a server in the sidebar, choose it in the app menu, or press Switch in Settings → General → Servers (the current one shows Browsing). Library pages show the active server.
• One queue: the queue can hold songs from different servers. Switching the browsing server does not clear it.
• Edit: press Edit next to a server in Settings → General → Servers to open the Edit server dialog.
• Remove: click the cross next to a server (Remove server), then confirm with Yes. In Settings the button reads Remove. This only removes the entry and its saved password from Listen, not anything on the server.

Editing a server

The Edit server dialog shows the Name and, depending on the source:

• Navidrome and Jellyfin: Server URL, Username, Password (leave it empty to keep the saved one) and the option switches above. Saving checks the connection first (the button reads Checking…).
• Navidrome only: Server music folder (optional) and Local music folder. If your server’s music folder is mounted on this computer (for example /music on the server and /mnt/nas/Music here), fill in both so that Show in file manager works for those songs. Leave them empty to hide that action.
• Local: Music folder.
• YouTube Music: change the channel, switch browser or Reconnect (read the cookies again). See YouTube Music.

When a server needs attention

If the server you are browsing cannot be used when Listen starts or when you switch to it, Listen shows a page with the reason instead of an empty library.

Both pages also offer Add a server, a list of Your other servers with Use and remove buttons, and a way to remove the failing server. If you have downloaded songs, Play downloaded songs (offline) opens them without a server. See Downloads.

Next steps

• The window for a tour of the interface.
• Library pages for browsing what you just connected.

YouTube Music

This page explains how to connect YouTube Music to Listen, what works, and what to do when sign-in fails.

Note: YouTube Music support is unofficial. Listen is not affiliated with or endorsed by Google or YouTube. It uses YouTube Music’s web interface and the separately installed program yt-dlp, may stop working whenever YouTube changes something, and may not be allowed by YouTube’s Terms of Service. You use it with your own account and at your own risk; YouTube may restrict accounts it considers to be accessed by unofficial clients. A YouTube Music Premium subscription is recommended.

How sign-in works

YouTube Music does not let third-party apps sign in with Google directly. Instead, Listen uses the YouTube session of a browser you already use on the same computer. You never type your Google password into Listen.

Listen stores only which browser profile and which channel to use. The cookies themselves are read again from the browser at every start and, while Listen runs, whenever YouTube has rotated its session cookie — an old one is answered as signed out, which used to empty the library and the playlists until the next restart. They stay on your computer and are sent only to YouTube. This means Listen stays signed in for as long as the browser does.

Supported browsers: Firefox, Chrome, Chromium, Brave, Edge, Vivaldi and Ecosia, plus the Flatpak versions of Firefox, Chrome, Chromium, Brave and Ecosia.

Sign in with a browser

1. Sign in to music.youtube.com in one of the browsers above.
2. In Listen, open Add server and choose the YouTube Music tab. Listen looks for a signed-in browser and shows a button such as Sign in with Firefox.
3. Press it. If your Google account has more than one YouTube channel (a personal one and one or more brand channels), Listen asks Which <browser> channel has your music? and lists the channels. Pick the one that holds your music library.
4. Listen connects and opens your library.

If the library looks empty, you probably picked the wrong channel. Open Edit on the server (see below) and choose another one.

Use another browser

If several browsers are signed in, possibly with different Google accounts, press Use another browser. Each entry shows its state, for example “signed in to YouTube”, or the reason it cannot be used. If a browser has several profiles, the profile folder name is shown in brackets. If no browser is found, the page shows why and a Look again button.

The browser is open

Chromium-based browsers keep their cookie file locked while they run. If Listen reports that the browser keeps its cookies locked, close the browser completely (including background processes and tray icons) and try again.

Windows: Chrome, Edge and Brave

Recent versions of Chrome, Edge and Brave on Windows encrypt their cookies in a way that only the browser itself can read (“app-bound” encryption). Listen then shows a message to that effect. You have two options:

• Sign in with Firefox, which stores its cookies unencrypted. This is the simplest way.
• Use a cookies file (next section).

Cookies file

1. In a browser where you are signed in to music.youtube.com, export the site’s cookies with an extension such as Get cookies.txt LOCALLY. JSON and cookies.txt formats work; a Cookie-Editor JSON export and a raw Cookie header work too.
2. In Listen, open Add server, choose YouTube Music and press Other ways to connect (cookies file, guest).
3. Press Browse… and pick the file, drop the file onto the window, or paste the cookies into the field below.
4. Press Connect with cookies / as guest.

Listen keeps only the cookies a browser would send to music.youtube.com and needs the SAPISID cookie among them. A cookies file stops working when you sign out of YouTube in the browser it came from.

Guest mode

In the same Other ways to connect section, leave the file and the paste field empty and press Connect with cookies / as guest. As a guest you can search, open albums and artists, start radio and play songs. You have no personal library, likes, playlists or history.

What works

When you are signed in:

• Your library: liked songs, saved albums, artists, and playlists, including creating, editing and reordering them. An Uploads list appears if you have uploaded music.
• A home feed of quick picks, mixes and albums.
• Search, album and artist pages, radio and Auto-DJ based on YouTube’s “play next” lists, and lyrics.
• Music videos for YouTube Music songs, with the song/video switch in the player bar. See Music videos.
• Playing a song reports it to YouTube Music, so your history and recommendations stay current there.
• Mixing YouTube Music songs with DJ transitions, once you switch on Analyse YouTube Music songs and choose an analysis folder. See Song analysis.

Your own copy of a song

When a YouTube Music song is also on one of your own servers (Navidrome, Jellyfin or a local folder), Listen plays that copy, which usually sounds better. It looks the song up by title and artist when the song enters the queue, ignores things like “(Official Video)”, “(Remastered 2011)” or “- Topic”, compares the length, and never swaps a live, remix, instrumental or karaoke version for a different one. If nothing is found, or the server does not answer in time, the YouTube Music version plays.

The song stays a YouTube Music song: likes, playlists, radio and the music video work as before, and the play is reported to YouTube Music and also to the server that played it. A small server icon next to the title shows the swap; hover it to see the server, and press it to play the YouTube Music version instead (and again to go back). The video switch keeps working: the video runs silently alongside the server’s audio.

Turn it off with Settings > Playback > Prefer my own servers for YouTube Music songs. See Music videos for how the picture is lined up.

Audio is streamed, not saved. Listen does not download YouTube Music songs for offline use, and the offline download feature works only for your own servers.

Requirements

yt-dlp finds the audio stream of each song. It is a separate program, and it needs a JavaScript runtime (Deno or Node.js). On Windows the first-start wizard installs both; on Linux install them with your package manager (see Installation).

Managing the connection

Open Settings → General → Servers and press Edit next to the YouTube Music entry. The dialog offers:

• Change channel… to list your channels and pick another one.
• Use <browser> instead to switch to a different signed-in browser.
• Reconnect (read the cookies again) after you signed in again in the browser.

When something stops working

YouTube changes things often.

• Songs do not play, or play only some of the time. Update yt-dlp first. On Fedora: sudo dnf upgrade yt-dlp. On Windows: Settings → Advanced → Updates → Helper programs → Update.
• The library is empty or errors appear. Listen reads the browser cookies again by itself when YouTube reports it as signed out, so this normally clears up without a restart. If the library still stays empty, press Reconnect in the edit dialog, then check the channel. If it still fails, a new Listen version may be needed; see Updates.
• Sign-in fails after you changed your Google password or signed out in the browser. Sign in to music.youtube.com in the browser again, then reconnect.
• Windows security warnings. Some antivirus programs find reading a browser’s YouTube sign-in unusual. Listen reads only the cookies of youtube.com and music.youtube.com.

You can also run listen --check-youtube-music in a terminal to see what Listen can see (channels, counts and whether playlists and albums open) without starting the interface. It never prints cookies. See Troubleshooting.

Updates

This page explains how Listen finds and installs new versions, and how to control it. Updates come from the project’s public GitHub releases; no account or token is needed.

How it works

When Listen starts, it asks GitHub for the list of releases (if Check on start is on). If there is a newer version for your release channel, an Update available dialog opens. It shows the new version, the release notes and what installing will do. Nothing is installed without your confirmation.

When you press Download and install, Listen downloads the package for your system together with the release’s SHA256SUMS file and checks the package against it. If the checksum does not match, nothing is installed. A release without a SHA256SUMS file cannot be installed by the updater.

What happens next depends on how you installed Listen:

After an RPM or tarball update the dialog says “Installed. Restart Listen to use the new version.” Press Restart now, or Later.

If Listen cannot update itself, the dialog explains why instead. This happens for a development build, for a Windows copy that was not set up by the installer (download the new installer from the release page), and for a program installed somewhere else, such as a package from another distribution (update it with the tool you installed it with).

The choices in the dialog

Skipping and reminding only affect the automatic dialog at start. You can always open the update yourself in the settings.

Settings

Everything is in Settings → Advanced → Updates.

The first-start wizard has the same switch as Check for updates.

Notes

• A manual Check now always opens the dialog when an update exists, even if you skipped it or asked to be reminded.
• Updates are not checked in demo mode (listen --demo) or with --ephemeral.
• Switching to Beta is safe to undo: switch back to Stable and you are offered full releases again, but Listen does not downgrade by itself.
• Update checks are one of the few things Listen contacts without you adding a service. See Privacy and security. If you do not want them, switch Check on start off.

The window

This page describes how Listen’s main window is laid out: the sidebar, the title bar, the page area, the player bar and the side panels, and how the layout changes when the window gets narrow.

Overview

In the normal layout the window has these parts:

Listen remembers the window size, its position and whether it was maximized. On Wayland a program cannot place its own window, so only the size and the maximized state come back there. The window starts at 1600 x 950 px the first time, and it cannot be made smaller than 480 x 120 px. See Tray, window and notifications for tray behaviour, single-instance start and sleep prevention.

The sidebar

The expanded sidebar has an action bar at the top and a scrollable list below it.

Action bar

Sections

From top to bottom the list holds:

1. Servers: every server you added, with its type and Add server. Click a server to browse it; playback of the current queue continues. A server that is not connected shows “not connected”. The small remove button next to a server asks for confirmation. This section is not shown in the demo library (listen --demo).
2. My Library: the pages you chose (see Choosing and ordering the pages), followed by Downloads and, on Linux with a CD drive attached, Rip CD (see CD ripping).
3. Collections: saved sort and filter combinations of the Albums and Tracks pages. The section only appears when you have saved one. See Collections.
4. Playlists: your playlists, with a + button to create one.
5. Shared Playlists: playlists other people made that you can see. Only shown when there are some.

Each of the last four sections has a header with a chevron; click it to fold or unfold the section. Listen forgets which sections you folded when it restarts.

Choosing and ordering the pages

Open Settings → General → Sidebar. Sidebar configuration lists every page. Tick a page to show it, and drag the grip on its left to move it.

A page that the current server cannot offer is hidden even when ticked. For example, YouTube Music has no Folders or Album artists, and only Navidrome and OpenSubsonic servers have Folders and Radio. Downloads is always shown.

Playlists in the sidebar

These rows are under Settings → General → Sidebar:

With folders on, a header button expands or collapses all folders at once.

You can drop songs on one of your own playlists in the sidebar to add them; see Drag and drop.

Collections

A collection is a saved query: the sort, its direction, the search text and the filters of the Albums or Tracks page. To save one, set up the page the way you want it, click the bookmark button (Collections) in the page header, type a name under Save these filters as… and press Save.

In the sidebar, click a collection to open the matching page with that query applied. The three dots next to a collection offer Rename and Delete. See Lists, selection and menus for the controls themselves.

The collapsed rail

When you collapse the sidebar it becomes a rail 84 px wide. It shows:

• optionally the back and forward arrows,
• a Menu button that opens the app menu,
• one icon with a small label for each page you enabled, plus Downloads, Rip CD (when a disc is present), Search and Settings, which the rail always shows,
• a Collections button that opens a menu of your collections (only if you have some),
• your playlists as small covers, under a Playlists heading. The chevron there hides or shows the covers and + creates a playlist.

You can collapse and expand the sidebar in three ways: the collapse button in the action bar, Collapse sidebar / Expand sidebar in the app menu, or by dragging the sidebar’s edge (see Resizing).

If you expanded the cover of the playing song into the sidebar (the arrow that appears on the cover in the player bar), the cover shows large at the bottom of the expanded sidebar, and floats next to the rail when it is collapsed. Click it to open the full-screen player. Settings → General → Player bar → Expand album art button turns this arrow off.

The app menu

The Menu button in the sidebar opens a small menu. Its entries are:

Title bar

By default Listen draws its own 30 px window bar. Choose its look in Settings → Window → Window bar style:

• Windows: the app icon and the playing song on the left, minimize, maximize and close on the right. This is the default.
• macOS: round red, yellow and green buttons on the left and the title centred.
• Native: your desktop draws the frame and Listen shows no bar of its own.

You can drag the custom bar to move the window, double-click it to maximize or restore, and right-click it for the desktop’s window menu. With a custom bar the window can be resized by dragging any edge (5 px wide) or corner (10 px). Track info in window title (same section) controls whether the playing song is shown in the bar and in the window title. In private mode the title says so.

The page area

The page area shows whichever page you opened. Pages are described in Library pages.

Right-hand panels

The queue panel on the right (or under the page) can show three panels: the queue, the lyrics of the playing song and a visualizer strip. Open Settings → Playback → Player sidebar panels:

Two settings in Settings → Playback → Queue change how the whole panel sits in the window:

• Side play queue style: Attached (a panel next to the page) or Detached (a drawer that slides in when you rest the pointer on the right edge).
• Side queue layout: Horizontal (a column on the right) or Vertical (a panel under the page).

The panel is hidden on the Now Playing page, because that page shows the queue itself, and in the full-screen player. The queue is described in Player bar and queue.

Resizing

Drag the thin divider to resize:

Your sizes are saved.

Compact layout and the mini player

There is no separate mini-player window. Instead, Listen switches to a compact layout whenever the window is 768 px wide or narrower, so shrinking the window gives you a small player. There is no button for this; it follows the window width, and the layout switches back above 768 px.

In the compact layout:

• The sidebar and the side panels are gone. The page fills the window above a 90 px player bar.
• A floating Menu button at the bottom left of the page opens the sidebar as a 320 px drawer over the page. Click outside the drawer or press Esc to close it. The button is hidden when the window is less than 192 px high.
• The player bar shows the cover, the title with a three-dots song menu, and previous, play and next. The speaker button opens a vertical volume slider.
• The full-screen player switches to a phone-style layout with shuffle, repeat, queue, lyrics and video buttons.

At the smallest size, 480 x 120 px, little more than the player bar fits, which makes a compact strip for keeping music controls beside other windows.

The settings Player bar button size, the skip buttons and the volume options are in Settings → General → Player bar.

Where to go next

• Library pages for what each page shows.
• Lists, selection and menus for tables, grids and right-click menus.
• Themes and colours for fonts, zoom and colours.
• Hotkeys for keyboard shortcuts.

Library pages

This page describes the pages you reach from the sidebar: the home feed, albums, artists, tracks, genres, folders, favorites and the pages built from your listening history. The tables, grids and menus that appear on these pages work the same everywhere and are described in Lists, selection and menus.

What a page shows depends on the server you are browsing. Navidrome and OpenSubsonic servers offer everything. Jellyfin, YouTube Music and local folders have no folders page, and some have no genres or radio. A page the current server cannot provide is left out of the sidebar. The table at the end of this page lists the differences.

Home

The home page is a feed of carousels.

Featured carousel. At the top, a banner shows random albums from your library with a large cover, the album’s genres and year, and a Play button (the label follows your play button behavior). Use the round arrows at the sides to move on. With the pointer over the banner, Shift plus the mouse wheel also steps through it. In Settings → General → Home you can switch it off (Home featured carousel) or choose Home featured carousel style: Single (one album, the default) or Multiple (a row of two to six albums, depending on the window width).

The server’s own feed. YouTube Music has a home feed of its own, with shelves such as quick picks and mixes made for your account. Its shelves come first. The other sources have no feed of their own.

New from your artists. With YouTube Music as the active server and your own listen-server set up (Merge with other devices in Settings → Advanced → Listening history), the first shelf shows the albums and singles that came out from the artists you follow on YouTube Music and the 50 artists you played most in the last year. The server reads their artist pages once a day with the YouTube Music session the phone shared, at most 200 requests a day, and lists a release from the day it first saw it for 60 days. The first time it reads an artist, only releases from this year count. A deluxe edition, repackage, remix release or other version of a release that is already known is not shown again. Click a card to open the album. The shelf needs listen-server 0.7.0 or newer; switch it off with New from your artists in Settings → General → Home.

Sections. Below that come the sections, in this default order:

Each carousel shows as many cards as fit the window. Use the arrow buttons in its header, drag the row sideways, or hold Shift and use the mouse wheel to move along it. Listen loads 20 more cards when you get near the end. The refresh button in a section’s header loads it again.

To choose which sections appear and in what order, open Settings → General → Home → Home sections. Tick a section to show it and use the up and down arrows to move it.

If the page says “Your library looks empty.”, the server returned nothing for any section.

Albums

Albums lists every album on the server. It starts as a grid of covers and loads more as you scroll.

The header holds the page title and the number of albums (shown as “250+ albums” while more are still loading), a Play button and a Shuffle play button that play everything the current search and filters match (up to 20,000 songs), and these controls:

• Sort by and a button for ascending or descending order. The options depend on the server. Navidrome offers, for example, Album artist, Artist, Duration, Most played, Name, Random, Rating, Recently added, Recently played, Song count, Favorited and Release year.
• Filters, the funnel button, with filters such as Favorited, Rated, Compilation, Recently played, Artists, Genres, Year and custom tags. Which ones exist depends on the server.
• Refresh.
• Collections, the bookmark button, to apply or save a query.
• A Search box.
• The buttons for table, grid and detail view and the list options. See Displays.

Listen remembers the sort, order and filters of the Albums and Tracks pages between sessions.

Album page

Click an album anywhere to open its page.

The header shows the cover, the release type (Album, EP, Single, Compilation, …) and the version if there is one, the title, a line with release date, number of tracks, running time, an “Explicit” mark, size on disk and play count, and the album artists as links to their pages.

Below that are the buttons:

• Play (or Add next / Add last, following your play button behavior), then Add next and Add last. The chevron next to them opens Shuffle, Add next shuffled and Add last shuffled. Holding the main Play button for half a second plays the shuffled version.
• Start radio, if the server can find similar songs.
• Five stars to rate the album (Navidrome and OpenSubsonic servers).
• A heart to add the album to your favorites. On YouTube Music this saves the album to your library.
• More options, the three dots, which opens the album’s context menu.

A toolbar has a Search box that filters the tracks, a sort menu for the tracks (the album’s own order by default, or title, artist, duration, play count, rating, year and more), an order button and the list options. When an album has several discs and you are not searching or sorting, the tracks are grouped under Disc 1, Disc 2 and so on, with the disc title when the server knows it. Tick a disc header to select all its tracks.

A long album comment is shown under the toolbar and can be expanded with Show more.

At the bottom of the page you find, where the data exists:

• the genres, as links to the genre pages,
• tags (release type, release country and status, Explicit), the record label, moods and groupings,
• External links, see External links,
• a copyright line with the label,
• More from carousels: one for the first album artist and one each for up to two of the album’s genres. The genre carousels have a refresh button that picks other random albums.

Artists and album artists

Listen separates two lists, as Navidrome and Feishin do:

• Album Artists: artists that appear as the album artist of at least one album. This is usually the list you want. YouTube Music has no album artists.
• Artists: everyone credited on a track, including guests and composers. On YouTube Music this page shows the artists you subscribe to.

Both pages are grids of portraits by default, with the number of albums and songs. They have no sort or search box; use the command palette to find an artist by name. Click an artist to open the page.

Artist page

The header shows the portrait, ARTIST, the name and a line such as “4 albums, 52 tracks, 3 hr 20 min”. The buttons are Play, Shuffle, Add next, Add last, a radio button (when the server supports it), a heart, five stars (Navidrome only) and three dots, which reveal Refresh and Copy name.

Below the header there are shortcuts: VIEW DISCOGRAPHY, VIEW ALL TRACKS and ARTIST RADIO; the artist’s genres as buttons; and EXTERNAL LINKS. Then the sections follow in the order you chose:

In Settings → General two sections control the page:

• Artist page: Artist page configuration (tick sections and reorder them), Artist release type configuration (which release types to show and in which order the groups appear) and Artist radio count (how many songs an artist radio queues; 20 by default).
• External links: see below.

External links

Artist pages and album pages can show small buttons that open other websites in your browser. In Settings → General → External links you can switch the whole feature off (External links) or choose each site:

Listen only builds the address. Nothing is sent to these sites until you click a button.

Tracks

Tracks lists every song on the server as a table. Like the Albums page it has Play, Shuffle play, sort, filters, refresh, collections and search, and it loads more rows as you scroll. The default columns are the number, a cover with title and artist, duration, album, genre, year and a heart. You can change them in the list options (see Columns).

Genres

Genres lists the genres with their album and song counts. It has a Search genres box, a sort menu (Name, Album count, Song count) and an order button. Click a genre to open it.

A genre page shows either the albums or the tracks of that genre. Switch with the Albums and Tracks buttons; the choice is remembered. Both lists have the same sort, filter and search controls as the Albums and Tracks pages, without the genre filter.

Folders

Servers that organise music in folders (Navidrome and OpenSubsonic) have a Folders page. The left side is a tree: All folders at the top, and folders that open with a chevron and load their sub-folders on demand. The right side shows a trail of the folders you are in, the sub-folders as a strip with a play button each, and the tracks directly in the open folder as a list. The buttons above the list are Play, Play next, Play last, Shuffle and Refresh. A right-click on a folder opens a menu that plays or queues everything inside it, including sub-folders, or adds it to a playlist.

For folders on your own computer, see Connecting your music; a local folder source does not have a folder browser.

Favorites

Favorites collects what you marked with a heart. On servers that can favorite albums and artists it has three tabs: Tracks, Albums and Artists. On YouTube Music the tabs are named Liked Music, Saved albums and Subscriptions. A Play button plays the tab’s songs. If nothing has a heart yet the page says “No favorites yet.” (or “Nothing liked yet.” on YouTube Music).

Show or hide hearts everywhere with Settings → General → Lists → Show favourites.

Other pages

Recently played, Statistics and Mixes are described in History, statistics and mixes.

What each source offers

YouTube Music support is unofficial. See YouTube Music for what that means and how to sign in.

Lists, selection and menus

Almost every page in Listen shows a list of songs, albums, artists, playlists or genres. They all share the same component, so they all look and behave the same way. This page explains the displays, columns, sorting and filters, how selection works, what the keyboard and mouse do, drag and drop, and the right-click menus.

Displays

A list can be shown in up to three ways. When a list offers more than one, two or three small buttons appear in its page header (Table view, Grid view, Detail view).

Song lists, genres, the queue and search results for tracks are always tables.

By default the Albums, Artists, Album Artists and Playlists pages start as a grid. Every other list starts as a table.

The look of a list (display, columns, sizes) is saved per kind of list, so all playlists share one look, all album grids share one look, and so on. The tracks of an album, the songs of a playlist, the queue panel and the Now Playing page each have their own.

List options

The sliders button in a page header opens List options. What it contains depends on the display.

Display switches between table, grid and detail (when more than one is offered).

Table options

Columns

Under Columns every column the list can show has a line with:

• a checkbox to show or hide it,
• up and down arrows to move it,
• L and R to pin it to the left or right edge, so it stays in view when the table scrolls sideways,
• an alignment button (left, centre, right),
• Fit, which makes the column as wide as its longest value.

You can also work directly in the table header: drag a column title onto another to reorder, and drag the right edge of a title to change the width.

The columns available for songs are: album group, number (#), image, title (three variants: name only, title and artist, or cover with title and artist), duration, album, album artist, artist, composer, date, genre, genre badges, year, release year, release date, disc, track, bit depth, bitrate, codec, sample rate, last played, comment, channels, BPM, date added, path, plays, size, favorite, rating and actions. Albums, artists, playlists and genres have shorter sets (for example, albums offer song count, release type and last played; playlists offer owner and duration). A column that no source can fill is not offered, and a column the server has no data for stays empty.

The default song table shows the number, cover with title and artist, duration, album, genre, year and a heart. The songs of an album show track number, title, duration and heart in compact rows.

The Album group column groups the rows of a song table by album under a header with the cover, facts, a favorite heart and a rating. When you enable it, an Album group section appears in the options: the cover size (No cover, 64 to 160 px), which facts to show (album artists, release date, release year, song count, duration, release type, genres, size), Favorite and rating and Cover above the facts.

Grid options

Hovering a card shows round buttons on the cover: play, Play next, Play last, the heart, More options and, for albums, a chevron that expands the album’s track list in a panel under the row.

Loading

Infinite scroll (the default) loads more rows as you scroll. Pages shows a fixed number of rows and a bar at the bottom (“1-100 of 1250”, Previous page, “Page 1 of 13”, Next page). Items per page is 100 by default and changes in steps of 25.

Reset to defaults puts the list back as it was.

Sorting, searching and filtering

The Albums page, the Tracks page and the albums and tracks of a genre have a header with these controls:

• Sort by opens a menu of sort fields. The fields depend on the server: Navidrome offers the most, plain Subsonic servers and local folders offer a few. Tracks can be sorted by album, album artist, artist, BPM, duration, favorited, genre, name, play count, rating, recently added, recently played, release year and more.
• The arrow button toggles ascending and descending order. Each sort field starts in its natural direction (for instance, “Most played” starts descending).
• Filters opens Album filters or Track filters. See below.
• Refresh loads the list again.
• Collections (Albums and Tracks pages) lists your saved queries and lets you save the current one.
• Search filters by text after you stop typing for a moment (about 0.4 seconds). The cross button clears it.
• Play and Shuffle play play everything the current sort, search and filters match, up to 20,000 songs. Hold Play for half a second to play it shuffled.

Other lists (artists, genres, playlists, search results) have their own simpler controls, described on their pages. In table views the column titles do not sort; use Sort by.

Filters

The filter window offers the filters the server supports, so you may not see all of these:

On plain Subsonic servers only one of Favorited, Artists, Genres and Year can be used at a time; the others show “Off while another of these filters is on”. Reset clears all filters, Done closes the window. The filter button lights up while a filter is active.

Listen remembers the sort, order, search and filters of the Albums and Tracks pages and of genre pages between sessions.

Collections

To save the current sort, order, search and filters as a collection, click Collections, type a name in Save these filters as… and press Save. A saved collection appears in the same menu and in the sidebar. Click it to apply it. The bin button in the menu deletes it; in the sidebar the three dots offer Rename and Delete.

Selection and clicking

Listen’s selection rules differ a little from Feishin’s, so they are worth knowing.

When something is selected, a bar at the bottom of the list shows “3 selected” with Clear and More. More opens the context menu for the whole selection.

A double-click on a song plays it and, with the default Play button behavior of Play now, queues up to 50 songs before and after it from the same list, so playback continues through the list. The queue panel itself behaves differently: a double-click there jumps to that song without replacing the queue.

In a grid the same rules apply to the whole card. If you turn off Settings → General → Lists → Grid multi-select, a click on the cover opens the item immediately.

Play button behavior

Settings → General → Lists → Play button behavior decides what the main Play buttons, a double-click on a song and the list’s play key do:

Shuffle play, the Auto-DJ and the AI DJ do not depend on it. The other rows of the Lists section are Grid multi-select, Show favourites (hearts everywhere) and Show ratings (star ratings, for Navidrome and OpenSubsonic).

Keyboard

Keys act on the list you are looking at, when no text field has the focus.

Enter, Ctrl+G and Ctrl+L are hotkeys you can change in Settings → Hotkeys; there are also optional hotkeys for List: play now, List: play next and List: play last. See Hotkeys. The context menu has its own keys: Up and Down move, Right opens a submenu, Left closes it, Enter runs the entry and Esc goes back or closes the menu.

Hover controls

Move the pointer over a row and its # column turns into a play button that follows the play button behavior. Rest on it for a moment and a small bar offers Play now, Play next and Play last. A right-click on the button opens the same three choices. The Actions column (three dots), when shown, opens the context menu. Hearts and stars in the Favorite and Rating columns work with one click; clicking the same star again clears the rating.

Drag and drop

Press on a row or card and move more than 6 px to start dragging. If the row is part of a selection, the whole selection is dragged. A small label follows the pointer. Drop it on:

• the queue panel (or the Now Playing page): the items are inserted where you drop them. Dragging rows within the queue reorders them. Dropping on an empty queue starts playing.
• one of your playlists in the sidebar: the items are added to that playlist. Playlists you cannot change do not accept drops, and neither does the sidebar while Sidebar playlist sorting is on (dragging then reorders the playlists).

Albums, artists and playlists that you drop are expanded into their songs first.

In a playlist’s edit mode, rows are dragged by a grip instead; see Playlists and smart playlists.

Context menus

Right-click any song, album, artist, playlist, genre or folder, or choose More options (three dots), to open its menu. The menu acts on the whole selection. Entries that the current server cannot do, or that do not apply, are left out. The footer of the menu previews what it acts on.

Songs

On rows of the play queue the menu starts with Remove from queue and has Move items (Move to top, Move to next, Move to bottom) and Shuffle (Shuffle selected, Shuffle all) as well. See Player bar and queue.

Albums

Play (side menu), Album radio (Play, Next, Last), Add to playlist…, Favorite (on YouTube Music: Save to library and Remove from library), Set rating, Download, Go to the album artists, Get info, Share… (on YouTube Music Copy link), Save file… and Clear selection.

Artists

Play (side menu), Artist radio, Add to playlist…, Favorite (on YouTube Music: Subscribe and Unsubscribe), Set rating, Get info, Share… or Copy link, Clear selection.

Playlists

Play, Shuffle, Play next, Add to queue, a Play side menu, Add to playlist… (adds all its songs to another playlist), Download, Open playlist, Edit playlist…, Edit smart rules… (smart playlists), Copy link (YouTube Music), Delete playlist…, Get info, Share…, Save file… and Clear selection. Editing and deleting only appear for playlists you own on a server that allows them. See Playlists and smart playlists.

Genres and folders

A genre has Play (side menu), Add to playlist… and Clear selection. A folder has the same, plus Share… and Save file… where the server allows it. A folder’s songs are collected recursively.

Get info

Get info opens a window with every fact Listen knows about the item. For a song that includes, where available, the id, title, artists, album, disc and track, year, genres, duration, codec, bitrate, sample rate, bit depth, channels, size, BPM, favorite, rating, play count, last played, dates added and modified, ReplayGain values, whether it has lyrics, the comment, MusicBrainz ids and the file path. Albums, artists and playlists show their own facts. Empty values are left out, and the server is asked for more details while the window is open. With several items selected, arrows step through them. A copy button next to a value copies it, a link button opens a MusicBrainz page, and the path of a local file has a Show in file manager button.

Edit metadata (local folders)

For songs from a local folder, Edit metadata… opens a tag editor. It edits Title, Artist, Album, Album artist, Track, Disc, Year, Genre, Comment and Lyrics, and the Cover: Use image (give the path of a PNG or JPEG file), Remove or Keep. You can select several songs; fields with different values show a hint and are left alone unless you type something. Preview changes lists exactly what will change, Write tags writes the files one by one, and Listen then rescans the folder. The files on disk are changed, so keep a backup if you care about the old tags.

Share links and copy link

On Navidrome, Share… opens Share item. Set Expiration with an amount and a unit, or use a preset (Server default, 1 day, 1 week, 1 month, 1 year), and optionally add a Description. Make default stores your choice as the default for new shares (you can also set it in Settings → General → Sharing). When you press Share, the link is created on the server and copied to the clipboard; the notification has an Open link button.

On YouTube Music, Copy link copies the public music.youtube.com address of the song, album, artist or playlist.

Save file

Save file… downloads the original, unconverted file from the server into your system Downloads folder (not Listen’s offline store). Several songs of one album go into a folder named after the album. If a file with that name exists, Listen adds a number such as “(2)”. A progress notification shows how far it is. Do not confuse it with Download, which stores a copy inside Listen for offline playback.

Search and the command palette

Listen has two ways to search: the command palette, a quick window you open from anywhere, and the search page, a full page with tabs. The palette can also jump to any page, switch servers and start a new playlist.

Both search the server you are currently browsing. With a local folder source they search that folder. If you want to search another server, switch to it first.

The command palette

Open the palette with Ctrl+K, with the Search box at the top of the sidebar, or with Open command palette in the app menu. Press Ctrl+K again to close it. You can change the shortcut under Settings → Hotkeys (the action is called Global search); see Hotkeys.

Start typing. After a short pause (about 0.4 seconds) Listen searches the server and shows up to five results per type under these headings:

Each heading shows how many results it has. Click the heading to fold or unfold it. View all opens the search page on that tab with your text, so you can see more than five.

Under the results is a Search group with these commands, which you can also reach with an empty box:

• Search for “your text” opens the search page with the same text.
• Create playlist… opens the new playlist dialog. Only offered when the server can create playlists.
• Go to page… opens a second page of the palette. The entries are Home, Search, Settings, Favorites, Recently played, Statistics, Mixes, Radio, Downloads under Pages, and Albums, Tracks, Album artists, Artists, Genres, Folders, Playlists under Library. Pages the current server does not have are left out. Typing narrows the list.
• Server commands… lists your servers under Select server (choose one to switch to it) and Manage servers…, which opens Settings → General.

Keys

The footer shows a breadcrumb of the pages you opened (click a part to go back) and the keys. The cross in the text box clears your text.

The search page

The search page is hidden in the sidebar by default. Show it with Settings → General → Sidebar (tick Search), or open it from the palette: Go to page… → Search, Search for “…” or View all.

Type in the box at the top. Listen searches while you type, after a short pause, and Enter searches at once. The results are in tabs:

• Tracks,
• Albums,
• Artists,
• Playlists, which appears when the server found some.

Once you have typed something, each tab shows its number of results, for example Albums (12). Listen asks the server for up to 100 results of each type. The box says “Type to search your library.” while it is empty, and the list says “No results.” when nothing matched.

Each tab is an ordinary list: you can switch between table and grid with the buttons at the right (albums and artists), change columns in the list options, select, drag and right-click exactly as described in Lists, selection and menus. Ctrl+F puts the cursor back into the search box (Local search in the hotkey list).

Describe it

With Merge with other devices set up (a listen-server address and token, see Continue on another device), the search page has a Describe it button next to the tabs. Turned on, the box takes a description instead of a title: “slow 90s Korean ballad”, “Brazilian samba with acoustic guitar”, “트로트”, “girl crush K-pop with heavy beats”, “dreamy lo-fi 80 bpm”. Press Enter to search (Listen does not search while you type in this mode). The results are songs only, best match first, up to 100.

Your listen-server ranks every song it has an embedding for by three things added together:

• how the music sounds: a 30-second clip of each song, compared with your words by the CLaMP 3 music-and-text model,
• what is known about the song: search tags (genre, decade, country, who sings, instruments, mood, scene names such as “city pop” or “1st-generation K-pop”) written once per song by Gemini from its artist and title, compared with your words by the same model,
• the words themselves: words of your description found in those tags or in the title.

A tempo in the description (“120 bpm”) becomes a filter: only songs within 6 bpm of it (or at half or double speed) are shown, using the tempo from the analysis store.

The embeddings come from listen-embed, a job that runs on a computer with a graphics card (tools/listen-embed in the source, see its README) and writes to Listen/embeddings next to the analysis store. Songs it has not reached yet are not found by Describe it; the server lists them at /v1/search/missing and counts them in /v1/status. Results play from the server they belong to: YouTube Music songs on your YouTube Music account, Navidrome songs on the Navidrome server whose address matches; songs of servers you have not added are left out.

The first search after a while takes a few seconds longer while the server loads its text model; turning Describe it on starts that loading.

What gets searched

What the search matches depends on the server:

• Navidrome, OpenSubsonic and Jellyfin search their library for song titles, albums, artists and, where supported, playlists.
• YouTube Music searches YouTube Music’s catalogue, not only your own library. Results from it are played through the unofficial YouTube Music support described in YouTube Music.
• Local folders search the files Listen found in the folder.

Filtering the lists on the Albums and Tracks pages is separate and works on your library only; see Sorting, searching and filtering.

Playlists and smart playlists

This page explains how to create, change and delete playlists, how to add songs to them, and how smart playlists work. Playlists live on your music server (or in your YouTube Music account); Listen does not keep playlists of its own.

What each source can do

Buttons for things a source cannot do are not shown. On YouTube Music you need to be signed in with an account; as a guest you can browse and play but not change playlists. A playlist you do not own, and YouTube Music’s built-in lists such as Liked Music, can be played but not edited. YouTube Music support is unofficial; see YouTube Music.

The Playlists page

The sidebar already lists your playlists, so the Playlists page is not in its list of pages by default. Show it by ticking Playlists in Settings → General → Sidebar, or open it from Go to page… in the command palette, or click the Playlists heading in the collapsed sidebar. The page shows your playlists as a grid or table. The header has:

• the title and the number of playlists,
• Play, which plays all listed playlists following your play button behavior,
• a Search box (matches name, owner and description),
• a sort menu with Name, Song count, Duration, Owner and Visibility, and an order button,
• Refresh,
• Create playlist and, on Navidrome, Create smart playlist,
• the display buttons and list options described in Lists, selection and menus.

Creating a playlist

Any of these opens the Create playlist window:

• the + button next to Playlists in the sidebar (or in the collapsed rail),
• Create playlist on the Playlists page,
• Create playlist… in the command palette,
• Add to playlist… on a song, typing a name in New playlist… and pressing Create (this creates the playlist with the selected songs in it).

The window has a Name, and, when the server supports it, a Description and a Public checkbox. Press Create. Playlists start private unless you tick Public. On Navidrome a public playlist is visible to the other users of your server.

Opening a playlist

Click a playlist in the sidebar, in the Playlists page, in the home page or in the palette. The top of the page shows:

• the cover,
• the word PLAYLIST, a Public or Private badge and, for smart playlists, a SMART badge,
• the owner, number of songs and total time,
• Play (or Add next / Add last per your setting), Add next, Add last and a chevron with the shuffled variants, and More options, which opens the playlist’s menu,
• the description, with Show more when it is long.

The toolbar below has:

Recommended songs

Below the last song of a playlist, Listen offers five Recommended songs that should fit it: your server’s own similarity (Navidrome’s and OpenSubsonic’s getSimilarSongs2, Jellyfin’s Similar) seeded with the playlist’s first, last and middle song, or a YouTube Music radio around them. Songs the playlist already has are never offered, and the five are picked at random from everything that fits, so the strip changes as you open playlists.

• a click on a recommended song plays it and the rest of the strip,
• the + at its right adds it to this playlist in one click; the row disappears and a message confirms it,
• the ↻ button next to Recommended asks for another five.

The strip is cached per playlist for ten minutes, so scrolling up and down or coming back to the page does not ask the server again; Refresh in the toolbar, or the ↻ button, asks again. Local folders have no server-side similarity, so they show no strip, and neither does an empty playlist.

Editing a playlist

Name, description, visibility and cover

Right-click the playlist (in the sidebar, the Playlists page or its own page) and choose Edit playlist…. Change the Name, Description or Public, and press Save. This is also how you rename a playlist. On YouTube Music the window reminds you that the current description and visibility are not shown; only the changes you make are sent.

If your Navidrome server can store playlist covers, small + and bin buttons appear over the cover of your own playlists. The + asks for an image file (PNG, JPEG, WebP or GIF, up to 10 MB). The bin removes the uploaded cover.

Changing the order

1. Open the playlist and press Edit.
2. Drag the rows by the grip in the first column to their new places. The row where you will drop it is outlined.
3. Press Save and replace and confirm “Replace the playlist with the new order? Are you sure?”. Press Cancel to throw the changes away.

In edit mode, Order for smooth mixing puts the songs into an order that mixes well, the way the DJs order their picks (see Order for smooth mixing). The first song stays first. Check the result, drag anything you want elsewhere, and press Save and replace to keep it or Cancel to throw it away.

To just listen in that order without changing the playlist, right-click it and choose Play in smooth order.

While you edit, search, sort and filters are switched off and the page shows the songs as tracks. Save and replace writes the whole playlist back to the server, so avoid editing the same playlist elsewhere at the same time. Edit is only offered for playlists you own on servers that can reorder (Navidrome, OpenSubsonic and YouTube Music). If you press it before a long playlist has finished loading, Listen tells you to wait.

Removing songs

Select one or more songs in the open playlist, right-click and choose Remove from playlist. After you confirm (“Are you sure you want to remove this song from …?”) the songs are removed from the playlist on the server. The songs themselves stay in your library.

Deleting a playlist

Right-click the playlist and choose Delete playlist…. The menu then asks “Delete …? This can’t be undone.” Choose Delete to remove it or Cancel to keep it.

Adding songs to a playlist

There are three ways.

From a menu. Right-click songs, an album, an artist, a genre, another playlist or a folder, and choose Add to playlist…. The menu turns into a picker:

• a Search playlists… box (it finds names even when you leave letters out),
• New playlist… and Create, to make a new playlist with these songs (only on servers that can create playlists),
• Skip duplicates, a tick box: songs already in the playlist are not added again. It is off by default, applies on Navidrome, OpenSubsonic and Jellyfin, and is not offered for YouTube Music.
• the list of your playlists, with the one you used last pinned at the top and marked with a star.

Click a playlist to add the songs. A notification says what was added. Albums, artists and folders are added as all their songs.

By dragging. Select songs, drag them to one of your playlists in the sidebar and release. See Drag and drop.

On YouTube Music the picker shows a check mark behind playlists that already contain the song, and does not let you add it to them again. Songs always go into the playlist on their own server, so a queue that mixes servers can only add to a playlist of the song’s source.

Smart playlists

A smart playlist has no fixed list of songs. It stores rules, such as “genre contains rock and rating is greater than 3, sorted by play count, limited to 50”, and the server works out the songs. Smart playlists are a Navidrome feature, and Listen edits them through Navidrome’s own API. They appear in the sidebar like any other playlist, with a SMART badge on the playlist page.

Creating and editing

Press Create smart playlist on the Playlists page. To change an existing one, press Edit rules on its page or right-click and choose Edit smart rules…. The editor window has:

A rule group has a selector, Match all or Match any, and the buttons Add rule and Add rule group. Groups can be nested inside each other. The top group also has Reset to default and Clear filters; nested groups have Remove rule group.

A rule is a Field, an Operator and a value:

The fields are the ones Navidrome knows, such as Name, Album, Artist, Album Artist, Genre, Year, Duration, BPM, Bitrate, Is Favorite, Rating, Play Count, Date Added, Date Last Played, File Path and many tag fields. If you use tags Navidrome indexes under other names, add them in Settings → General → Query builder → Custom fields: give each a Label, a type (string, number, boolean, date or playlist) and the Tag name used in rules. That section only exists while the server you browse supports smart playlists.

Press Create (or Save). The editor refuses an empty name, and shows the server’s message if the rules are not valid. Afterwards the playlist page opens and shows the songs the rules select.

Notes

• Smart playlists are computed by the server. Listen only edits the rules and shows the result, so the same list also appears in other Navidrome apps.
• The contents come from the rules, so change the rules rather than adding, removing or moving songs by hand.

History, statistics and mixes

Listen keeps a listening history on your computer. It feeds three pages: Recently played, Statistics (with a year review) and Mixes. This page explains what is recorded, how to control it, how to export or delete it, and what the pages show.

The history is never uploaded or shared. It is a plain text file on your computer, and everything on the three pages is calculated from it on demand. Deleting entries therefore also removes whatever was derived from them.

What is recorded

A song is added to the history when it counts as played, using the same rule as scrobbling: when you have listened to it for a set share of its length or a set number of seconds, whichever comes first. Skipping ahead in a song does not count as listening. The AI DJ’s spoken breaks are not recorded.

The rule is set under Settings → General → Scrobble:

Skips

When you leave a song for another one before it counts as played (Next, Previous, the album skip buttons, double-clicking another song in the queue, or starting another list), the history records a skip instead: the song, the position you left it at, the play mode and whether you or a DJ picked it. Leaving a song does not count as a skip when it was never really started (a restored queue you have not played yet), when Previous only restarts the song, or when the player moves on by itself: a DJ mix into the next song, the end of a song, or a song that failed to load (also when you start another song later, after a song ended on its own). Next on the last song of the queue stops playback and counts as a skip, because you left the song early. The AI DJ’s breaks and bridge songs are not recorded.

A skip is never a play: it does not count in the play numbers, the top lists, the mixes or Recently played, and it is never scrobbled. The Statistics page shows skips separately. A skip tells the DJs that a song did not fit at that moment.

The history works independently of the Scrobble switch: that switch only controls whether plays are reported to your server (for example to Last.fm).

Each entry stores the time, which server and song it was, whether it was played or skipped, the title, artists, album and length, and the cover address so that the list can be shown without asking the server. Newer entries also store the play mode, who picked the song (you, the Auto-DJ, the AI DJ) and which of your devices played it; skips store where in the song you left it. Songs from every source are recorded, including YouTube Music and local folders.

Settings

Open Settings → Advanced → History.

The CSV file has the columns timestamp (Unix seconds), server_id, source, song_id, status (played or skipped), title, artists (separated by semicolons), album and duration_secs. Text that a spreadsheet would read as a formula gets a leading apostrophe. The JSON file holds the same entries as a list.

The history itself is the file history.jsonl in Listen’s data folder; see Files and folders. You can back it up like any other file, and Backup, logs and diagnostics covers what else is worth keeping.

Private mode

Private mode stops three things at once: no entry is added to the history, no plays are scrobbled and Listen shows nothing on Discord. The window title says that private mode is on. It switches off again when Listen restarts.

Turn it on or off in any of these places; they all control the same switch:

• Menu → Private mode in the sidebar’s app menu,
• Settings → Window → Private mode,
• Settings → Advanced → History → Don’t record this session.

Recently played

Recently played lists the last 500 plays, newest first, as an ordinary song list. Double-click a row to play from it. To forget a single play, right-click the row and choose Remove from history. If you have switched the history off, the page says so instead of listing songs.

Statistics

Statistics summarises what you listened to. Buttons at the top choose the period: Last 4 weeks, All time, or one of the years that have entries. Listen opens on Last 4 weeks; picking a year shows that year, or the newest year with entries if the chosen one has none. The heading reads “Your 2026 in music” for a year and “Your listening, all time” otherwise; this is the year review.

The page shows:

• songs played: the number of plays in the period,
• listening time: the full length of each song you played past the scrobble point, added up,
• songs skipped: the number of skips in the period,
• Top songs, Top artists and Top albums: ten each, with play counts. Songs and albums also show their artist; the others show the listening time. Where a song, artist or album was also skipped in the period, the row adds “N skipped”.

The ranking breaks ties by listening time and then by name. The artist chart counts every credited artist of a play, so a song with two artists counts for both.

Last 4 weeks

The rolling view compares this week with last week. The periods are rolling and end now: this week is the last 7 days, last week the 7 days before that, and 4 weeks the last 28 days.

• Four tiles for this week: songs played, listening time, different songs and different artists, each with the change against last week (“+25 % vs last week”). When last week had nothing, the tile says “nothing last week”.
• New artists this week: artists with a play this week and no play at all before it, most played first, with the first song you heard from them. A skip alone does not count as having heard an artist.
• Skipped most (4 weeks): the songs you skipped most often in the 28 days, with how often you skipped and played them.
• The last 4 weeks: plays, listening time and skips of the 28 days, then the top songs, artists and albums of that period, counted the same way as the year view.

Mixes

Mixes builds playlists of up to 50 songs from your history. Open one to see its songs and play it. Each row is a normal song row with the usual menus, so you can add the whole mix to a playlist from there.

A mix without enough history behind it is greyed out and says “Not enough history yet”. Mixes change as you listen. They are made on your computer and need no server feature.

Learnable songs

With a vocab-hub address set (see Lyrics: known words), Mixes also shows Learnable songs: your liked songs where you know 90 to 98 % of the Korean words, the easiest first. Enough to follow the song, with a few new words to pick up. Songs with fewer than 20 Korean words are left out. Opening the mix loads your liked songs and looks up the lyrics of those not seen yet, a few at a time (the page shows how far it is); songs you played with lyrics are counted already. Songs without Korean lyrics are looked at again after 30 days. Every song’s words are kept in the cache folder (lyrics-words.json), so when you learn words in Lute the mix is counted again from there, without fetching lyrics again. Snoozed and “Not interested” songs stay out.

The artist page’s Top songs → Personal view uses the same history; see Library pages.

Related

• Search and the command palette lists the Statistics, Mixes and Recently played pages under Go to page….
• Privacy and security summarises what stays on your computer.

How Listen tells a forgotten favourite

Listen models how present each song is in your memory, after the ACT-R model from cognitive psychology: every play adds to a song’s “activation”, and the effect of a play fades with time (by the square root of its age). Many plays close together give a high peak; months of silence bring the activation down. A forgotten favourite has at least five plays, none in the last 30 days, and a large gap between its peak and its activation now. The Auto-DJ’s forgotten-favourite slot, the AI DJ’s song pool and the Rediscover mix use this ranking. A song you skipped again and again in the last week counts as worn out and rests from automatic picks for a while. Skips never count as plays.

listen --memory prints the current top 20 forgotten favourites and the resting songs as JSON (--history FILE, --now UNIX, --limit N).

Downloads

Downloads store copies of songs inside Listen so that you can play them without a network connection or when your server is down. This page explains which sources support it, how to download and remove songs, where the files are kept and what limits apply.

What can be downloaded

Offline downloads work for songs from Navidrome and other OpenSubsonic servers. Jellyfin servers and local folders do not offer downloads (a local folder is already on your disk). YouTube Music songs cannot be downloaded: Listen does not download YouTube Music songs for offline use, and it does not offer the command for them. Listen’s YouTube Music support is unofficial; see YouTube Music.

Note: Downloads are for your own server’s music. They are not a way to export your library to other programs. To save a normal file that you can use elsewhere, see Save file… below.

Downloading

Right-click a song, an album, a playlist or a selection (or use the three dots) and choose Download. Listen puts the songs in a queue and fetches them one at a time. While it works:

• a notification says “Downloading 12 songs…”,
• the Downloads page shows “Downloading “Title” (3 of 12)…” in blue,
• when the batch is finished you get “Downloaded 12 for offline play.” Songs that failed are counted too, and listed on the Downloads page with the reason.

Songs you already have are skipped (“Already downloaded.”). If the server is not connected or has no download support, Listen says so.

Listen downloads the file as the server stores it, not a transcoded version.

The Downloads page

Downloads is always in the sidebar, below your pages. It lists everything that is stored, sorted by artist, album and track number, and shows how many songs there are and how much space they use, for example “12 songs · 480 MB”.

To remove downloads from the context menu, select songs that are all downloaded and choose Remove download; the same entry replaces Download in that case.

Removing a song while it is being fetched cancels it. Removing a server from Listen also deletes all downloads from that server.

Playing offline

Whenever a song has a downloaded copy, Listen plays the copy instead of streaming it, even when the server is reachable. This also saves traffic and keeps playback working on a bad connection.

If Listen starts and cannot reach any server, the connection screen offers Play downloaded songs (offline), which opens the Downloads page. That page works without a connection, and so does the player. Browsing the library, search, lyrics lookup from the internet and similar features need a server or internet connection as usual.

Where the files are

Downloads live in a folder named offline inside Listen’s data folder (see Files and folders), with the audio in offline/files and an index file that remembers the song details. The folder is private: on Linux only your user can read it. A download counts only when it is complete; unfinished files (.part) are cleaned up when Listen starts. The file names are made of the server and song ids, so the folder is not meant to be browsed or used by other programs.

Limits

• Downloads are fetched one at a time, in the order you queued them.
• Listen sets no size limit of its own; the limit is the free space on the disk that holds the data folder.
• An empty or failed file is discarded and shown in the list of errors.
• Downloads are tied to the server they came from. If you remove the server from Listen, its downloads go too.

Download versus Save file

The context menu has two similar entries on Navidrome, OpenSubsonic and Jellyfin:

See Lists, selection and menus for details.

Player bar and queue

This page covers the player bar at the bottom of the window, the seek bar (slider or waveform), and the play queue in all its forms: side panel, drawer and the Now Playing page. It also explains the queue tools, the difference between songs you queued and songs a DJ added, how the queue is restored, saving it to your server and the sleep timer.

The player bar

The bar has three columns. On the left are the cover and the song information, in the middle the transport buttons and the seek bar, on the right the extra buttons and the volume. When the window is 768 px wide or narrower, Listen switches to a compact bar with a smaller set of buttons.

Left: song information

• Click the cover to open the full-screen player. The small arrow on the cover moves the cover into the sidebar and back.
• The title is a link to the Now Playing page. Artists and album are links to their pages.
• The ⋮ button next to the title opens the song menu. A right-click on the song information opens the same menu.
• While a DJ transition runs, the third line reads “Mixing into …”. While the AI DJ talks, its name and its line are shown instead of the song.
• While an internet radio station plays, the station name and the current stream title are shown.

Middle: transport buttons

From left to right:

On a narrow bar, Listen first hides the skip buttons, then Stop and “Shuffle all songs”. A radio station keeps only Stop and Play.

The skip buttons, their durations and the button size are set in Settings → General → Player bar (Show skip buttons, Skip backward duration, Skip forward duration, Player bar button size).

Seek bar and times

The seek bar sits under the buttons. Click or drag to seek; the time on the left follows the drag and the seek happens when you release. The time on the right is the song length. Click it to show the time left (for example -2:31) instead; the setting Show remaining time does the same.

Seeking while a DJ transition is running cancels that transition.

Waveform seek bar

By default the seek bar is a plain slider. To show the loudness curve of the song instead:

1. Open Settings → General → Player bar.
2. Set Playerbar slider to Waveform.

The played part of the waveform is drawn in your accent colour. A click or drag seeks, as with the slider. These extra rows appear once you choose the waveform:

Listen calculates the waveform from the song’s audio, so it has to read the whole song once. For a song on a server this means an extra download, which is why the setting warns against the waveform on slow or metered connections. The result is cached, so a song is analysed only once. The loading delay postpones the calculation after a song change; raise it if you hear stutter when songs change.

Until the waveform is ready, and for songs without usable audio input, the plain slider is shown. A YouTube Music song gets a waveform only when a local copy of its audio already exists; the waveform never causes extra requests to YouTube.

Right: buttons, rating and volume

The right-hand buttons can be reordered and hidden in Settings → General → Player bar → Right-hand buttons. The available buttons are:

• Sleep timer (see below).
• Player config, shown as Player options: output device, playback speed and pitch. See Sound.
• Visualizer and Lyrics: open the matching tab of the full-screen player.
• Favorite: the heart. It is hidden when Show favourites is off in Settings → General → Lists.
• Queue: shows or hides the queue panel (or drawer).
• Volume: mute button and slider.

Some buttons appear on their own when they apply: the Show video / Show song switch for YouTube Music songs (Music videos) and the cast button when speakers or TVs were found (Casting).

Ratings. When the song’s server supports ratings (Navidrome and other OpenSubsonic servers; never YouTube Music) and Show ratings is on, five stars appear above the buttons. Click a star to rate the playing song; click the same star again to clear the rating. The hotkeys “Rate 0 stars” to “Rate 5 stars” do the same.

Volume. Click the speaker to mute. Scroll the mouse wheel over the slider to change the volume by the Volume wheel step (5 by default). The slider width is Volume slider width. A right-click on the speaker opens the list of audio output devices. While you cast to a device, the volume control sets the device’s volume.

Open on click. If you switch on Player bar opens full-screen player, a click on an empty part of the bar opens the full-screen player.

The queue

The queue is the list of songs that play next. It can hold songs from several servers at once.

Where the queue is shown

Each place shows a header with the number of songs and the total time, a button naming the current play mode (a click moves to the next mode), and the queue itself.

Queue settings are in Settings → Playback → Queue:

Settings → Playback → Player sidebar panels controls what the right-hand sidebar holds. Besides the queue it can show a lyrics panel, a visualizer strip, or both combined in one panel, and you can set the Panel order. Drag the dividers between the panels to resize them. The queue panel itself can be switched off as long as another panel stays on.

Working with the queue

• Play a song: double-click it, or use the play button that replaces the number when you hover a row.
• Reorder: drag rows up or down. Drag songs, albums or playlists from any list and drop them between the rows (or on the empty area under the last row) to insert them. You can also drop onto an empty queue to fill it.
• Select: Ctrl+click toggles a row, Shift+click selects a range. See Lists, selection and menus for the details.
• Remove: select rows and press Delete or Backspace. The playing song stays.
• Search: the field in the toolbar filters the queue by title, artist, album or genre.
• Right-click (or the row menu) offers Remove from queue, Move to top, Move to next, Move to bottom, Shuffle selected and Order for smooth mixing. The last one reorders everything after the playing song so that each song flows into the next (see Order for smooth mixing). The Up Next block is ordered within itself and still plays first; DJ bridge songs in that part are dropped, because they were chosen for their old neighbours.

Songs that were analysed for the DJ features show their tempo and key after the artist (“Artist · 124 BPM · 8A”).

Queue tools

The toolbar above the queue has these buttons:

In a narrow queue the buttons fold into a … menu, from the least to the most important one.

Queued songs and DJ songs

The queue distinguishes three kinds of songs:

1. The rest of the queue: the songs of the album, playlist or list you started.
2. Up Next: songs you added with Play next (they go to the top of the block) or Add to queue (they go to the end of the block). They play right after the current song, ahead of everything else. With Up next queue on, the block gets “Up Next” and “Queue” label rows; with it off, such songs carry a Queued tag until they play.
3. DJ songs: songs the Auto-DJ or the AI DJ appended at the end. They carry an Auto or AI tag (a DJ bridge carries Bridge). Leaving the Auto-DJ mode does not remove songs it already added; delete them like any other song.

Why this song? Hold the pointer over the tag of a DJ song to see why it was picked. The Auto-DJ names one reason: a favourite you have not played for two months or more, “Similar to” the song its similar songs came from, “New to you”, or “Random pick from your library”. The AI DJ writes its own short note for every song of its set (at most 80 characters, in the DJ’s language, for example that the song keeps the key and lifts the tempo); a bridge says which two songs it links. Songs you added yourself have no reason. The reason of the playing song is also shown under the album in the full-screen player.

Dragging a row into the Up Next block adds it to the block; dragging it elsewhere takes it out. A marker row “AI DJ break” shows where the AI DJ will speak.

Player filters

Settings → Playback → Player filters keeps unwanted songs out of the queue. Press Add rule, then choose a field (title, artist, genre, year, play count, rating and others), an operator (for example contains, is, starts with, matches regex) and a value. A song that matches an active rule is left out when you play or queue it, and Listen says how many were kept out. Songs the Auto-DJ and AI DJ add are not filtered by these rules (use Snooze or Not interested for that, below). Each rule has an on/off switch.

Snooze, Not interested and Hide in this playlist

The menu of a song (in a list, in the queue and in the player bar) has three entries that keep it out of what Listen picks for you:

• Snooze 30 days: for 30 days the Auto-DJ, the AI DJ, song, album and artist radio, DJ bridges and the mixes (Daylist, Heavy rotation, Rediscover, All-time favourites) leave the song out. Then it comes back by itself.
• Not interested: the same, for good. For a YouTube Music song it also sends a dislike to YouTube Music, so its own suggestions learn from it (switch this off in Settings → Advanced → Hidden songs → Dislike on YouTube Music).
• Hide in this playlist (only in a playlist): the song is left out when you play that playlist; other playlists, albums and the DJs are not affected. Show in this playlist takes it back.

Every version of a song counts (the single, the album track, the music video). A song you pick yourself always plays, even when it is snoozed, not wanted or hidden; double-clicking a hidden song in its playlist plays it. Upcoming songs a DJ already queued go from the queue when you snooze or reject them; the song playing now plays on.

Settings → Advanced → Hidden songs lists every snoozed (with the days left), not wanted and hidden song with an Undo button.

With Merge with other devices on (Settings → Advanced → Listening history), the hidden songs go to your listen-server right after each change and with every history merge, so the phone and your other computers leave the same songs out. When two devices change the same song, the later change wins. This needs listen-server 0.6.0 or newer.

Queue restore

With Save play queue on, Listen writes the queue and the position of the playing song to disk every few seconds and when you quit. At the next start the queue is back, the playing song is selected and the position is remembered, but nothing plays by itself. Press Play to continue where you stopped. Shuffle and repeat are restored as well.

Saving the queue to your server

Navidrome and other OpenSubsonic servers can store one play queue per user, so that another app can continue where you stopped. The two buttons appear in the queue toolbar when the server you are browsing supports this.

• Save queue to server sends the songs of that server (songs from other servers are left out), the playing song and the position. A message tells you how many songs were saved.
• Restore queue from server replaces your queue with the saved one. Nothing starts playing; the first Play resumes at the saved position. If Confirm queue changes is on, Listen asks before replacing.

To save automatically, switch on Autosave play queue to server in Settings → Playback → Queue and set Autosave every (1 to 20 track changes; default 1).

Sleep timer

The Sleep timer button (a clock icon) in the player bar opens a small panel:

• End of song pauses at the end of the playing song.
• End of album pauses once the album of the playing song is over. If you start another song yourself, the timer follows that song’s album. It is not available while Shuffle is on.
• The grid starts a timer of 5, 10, 15, 30, 45, 60, 120, 180 or 240 minutes.
• Custom takes hours, minutes and seconds (up to 23 h 59 min 59 s).

While a timed timer runs, the remaining time is shown on the button. The countdown only runs while music plays, so pausing does not use up your time. When the timer ends, playback pauses and Listen shows a short message. Cancel in the panel turns it off. The sleep timer is not kept when you quit Listen.

Play modes and Auto-DJ

Listen has one button that decides what happens when the queue runs low: stop, shuffle, add similar songs (Auto-DJ) or let the AI DJ take over. Repeat is a separate button. This page explains both and the Auto-DJ settings.

The play mode button

The play-mode button sits in the player bar next to Stop. The same button appears in the header of the queue and on the Now Playing page, labelled with the current mode. Each click moves to the next mode:

Off, Shuffle, Auto-DJ, AI DJ, and back to Off.

The tooltip shows the current mode and the one a click leads to (“Play mode: Shuffle → next: Auto-DJ”). The “Toggle shuffle” hotkey, the media-key integration and the remote-control page use the same cycle. The MCP server’s set_play_mode tool can pick a mode directly. A highlighted button means any mode other than Off is on.

The modes exclude each other. If several settings were on together (for example from an older configuration), the order of priority is AI DJ, then Shuffle, then Auto-DJ.

A new installation starts in Auto-DJ. The first-start wizard can turn it off.

Note: The AI DJ is skipped in the cycle until a Gemini API key is saved. If you choose it anyway (for example through MCP), Listen shows a hint to add a key in Settings → Playback → AI DJ. See AI DJ and Creating a Gemini API key.

Shuffle changes the order of the queue itself, so you see the new order in the queue panel. The sleep timer’s End of album option is not available while Shuffle is on.

With the AI DJ on, clicking a single song in a list plays that song alone and makes it the new mood for the DJ’s next set, instead of queueing the whole list.

Repeat

The repeat button cycles Off, One, All:

• Off: the queue stops after its last song.
• One: the playing song repeats. Pressing Next still moves on, but stays on the last song instead of wrapping around.
• All: after the last song the queue starts again from the top.

The button is highlighted whenever repeat is on, and shows a “1” symbol for One. The hotkey is “Toggle repeat”.

Auto-DJ

The Auto-DJ keeps the music going without you filling the queue. It watches how many songs are left after the playing one. When at most one song is left, it asks the server of the playing song for songs similar to it, adds a few random songs as filler, and appends the best candidates to the end of the queue. Songs it added are tagged Auto-DJ in the queue. See Player bar and queue.

Details:

• Songs that already played in this session, and songs already in the queue, are not added again.
• Where a song exists in several versions (for example a studio version and a live version), one version is picked, preferring the radio edit.
• If songs were analysed, the picks are ordered so that tempo, key and energy follow on from the playing song. The Auto-DJ then looks at more candidates before choosing.
• With DJ transitions on, songs the Auto-DJ picked are mixed into each other.
• Forgotten favourites: every eighth song the Auto-DJ adds is one of your favourites that you have not played for at least 30 days (at least five plays in your history). Of those, the one whose tempo, key and energy fit the playing song best is taken. Its reason in the queue reads “A favourite, not played for 5 months”. Without such songs in your history the slot gets an ordinary pick.
• Worn-out songs rest: a song you skipped three times in the last seven days (or twice, if you also played it a lot that week) is left out of the Auto-DJ, the AI DJ, radio, DJ bridges and the mixes until those skips are more than a week old. You can still play it yourself at any time.
• Learn from my skips: how much a tempo gap, a key clash, an energy jump, a change of sound, a hard cut or a repeated artist count when the DJ orders its picks is learnt from your own listening. Every time a song you were playing hands over to one the Auto-DJ, AI DJ, radio or Rediscover picked, Listen notes whether you skipped the new song within 30 seconds. From these handovers (on every device, the history is synced) it fits how strongly each of those terms goes with an early skip, and weighs them that way. Until 300 handovers are recorded the learnt weights are mixed with the built-in ones in proportion (100 handovers: one third learnt), and below 300 a term can only count more or less, never the opposite way; below 30 handovers the built-in weights are used unchanged. A term your history says nothing about (for example no same-artist handovers yet) keeps its built-in weight. The fit is redone every ten plays or skips and kept in flow-weights.json next to the history. With Merge with other devices on, the fit also goes through your listen-server: the newest fit of any device is used everywhere, so the computer and the phone weigh the same way (a device that has not learnt anything yet never replaces a learnt fit with the built-in weights; needs listen-server 0.10.0 or newer). Turning the setting off brings back the built-in weights exactly. listen --flow-weights prints the number of handovers, the cross-validated AUC of the learnt weights next to that of the built-in ones, and each weight.
• What “similar” means depends on the server: Navidrome and Jellyfin use their similar-songs lists, YouTube Music uses its “watch next” list.

Settings

Open Settings → Playback → Auto-DJ:

Three more options exist that have no control in the settings window. They live in the configuration file under [settings.auto_dj] (see Files and folders), can be changed through the MCP server’s set_settings tool, and are filled in when you import your settings from Feishin:

Edit the file only while Listen is closed.

Focus

Focus is for working or reading while music plays: songs with lyrics distract most there. The Focus button sits next to the play-mode button at the top of the queue (and on the Now Playing page). It shows in Auto-DJ and AI DJ mode, and always while Focus is on. A green button means Focus is on; Listen remembers it.

With Focus on:

• The Auto-DJ and the AI DJ prefer songs with little lead vocal and calm energy. Listen knows how much of a song is sung from the analysis (the vocal level of every bar). Besides the similar songs, the Auto-DJ also looks at the least sung analysed songs in your history, so each fill finds quiet songs even when the similar ones are all sung. Songs without an analysis come last.
• A sung song the Auto-DJ picked is swapped for its instrumental version when its source has one (for example “Love (Inst.)” on YouTube Music, or an instrumental track on a Navidrome album). Listen searches for “title artist inst.” for up to three songs per fill; when that finds no instrumental it searches once more for plain “title artist” (some Navidrome searches miss “(Instrumental)” tracks with the extra word). The swapped song keeps its place in the queue, and its reason reads “Good for focus”.
• The AI DJ does not talk: no voiced breaks, not even planned ones. It still chooses and mixes the songs.
• No forgotten-favourite slot (a forgotten favourite is rarely a quiet one).
• Turning Focus on removes upcoming DJ songs that are sung, except the next one (it may already be mixing in). Songs you queued yourself stay.

Songs you start yourself always play as they are. Turn Focus off and the next fill is an ordinary one again. The MCP server’s set_focus tool switches it, and get_state reports it as focus.

listen --focus checks Focus on your own data: it splits your history’s analysed songs into Auto-DJ-sized candidate pools and prints, as JSON, the mean sung share of eight ordinary five-song fills and of eight Focus fills, and their ratio (--history FILE, --store DIR, --fills N, --per-fill N, --pool N, --seed N). Instrumental swaps come on top of that number.

Heart-rate tempo

The heart button next to the play-mode button plays songs whose tempo fits your heart rate, from a Bluetooth heart-rate sensor. In Off or Shuffle it switches to Auto-DJ. See Heart-rate tempo.

Heart-rate tempo

Heart-rate tempo plays songs whose tempo fits your heart rate, for a run, a ride or a workout at home. It needs Bluetooth on the computer and a Bluetooth heart-rate sensor that uses the standard Heart Rate Service: most chest straps do, and so do watches that can broadcast their heart rate. Listen does not stretch songs to the beat. It only chooses songs that already fit.

Music does not measurably change your heart rate during exercise. The mode picks music that fits your effort. It is not training guidance.

Switching it on

The heart button sits next to the play-mode button in the player bar, and next to the repeat button in the narrow full-screen player. You can switch it at any time. The song that plays keeps playing. The button is highlighted while the mode is on, and once readings come in it shows the target tempo (“142”). Its tooltip shows the status:

• Heart-rate tempo off
• Looking for a heart-rate source…: Listen is scanning for a sensor.
• No heart-rate source found: no sensor is in range, or Bluetooth is off or missing. Listen keeps looking every few seconds, and everything else works as usual.
• Heart-rate tempo on: readings come in. The tooltip also shows the target and the sensor’s name.

The Toggle heart-rate tempo hotkey, the switch in Settings → Playback → Heart-rate tempo and the MCP server’s set_heart_rate tool switch it too.

The tempo needs a DJ to choose the songs. In Off or Shuffle, switching the mode on also switches the play mode to Auto-DJ. In AI DJ the AI DJ keeps going. Switching the mode off leaves the play mode as it is.

The sensor

When the mode is on, Listen scans for a Bluetooth device that offers the Heart Rate Service. It connects to the first one it finds and subscribes to its heart-rate readings. The sensor is not paired with the computer. Listen remembers the sensor and looks for it first next time. Other sensors are only taken when it doesn’t show up within a few seconds. Settings → Playback → Heart-rate tempo → Forget sensor clears the remembered one. If the link drops (out of range, strap taken off), Listen connects again on its own.

Wear the strap before you switch the mode on. Most straps only send while they have skin contact.

On Linux, Listen talks to BlueZ (the system’s Bluetooth service) over D-Bus. On Windows it uses the system Bluetooth stack. The computer needs Bluetooth Low Energy (Bluetooth 4.0 or later). Step cadence (the phone app’s mode without a sensor) is not available on the computer.

How songs are chosen

Readings are smoothed over about 30 seconds, so one odd reading doesn’t change the music. The target is your heart rate in beats per minute, clamped to 70–180, ± 8 BPM. Half and double time count: at 150 a 75 BPM song fits, and at 70 a 140 BPM song fits. The fit is judged at the faster pulse, so at 70 the songs that fit are 62–78, 132–148 and 31–39 BPM. A 130 BPM song does not fit 70: it is 10 BPM off 140. Tempos come from the song analysis. Songs without one count as unknown, unless their tags give a BPM.

• Re-ranking. When the target has moved more than 5 BPM since the last time, the upcoming songs the DJs picked are sorted again. Songs within 4 BPM stay, closest tempo first, and the rest are taken out. The song right after the current one also stays, because it may already be loaded or mixing in. Songs you added yourself are never touched.
• Fills. Every Auto-DJ fill and every AI DJ set aims at the target. The fetched candidates that fit come first. When too few fit, Listen tops them up from the analysis store: songs from your history and analysed YouTube Music songs that fit, closest to the current song’s sound. Songs that are queued, played this session, snoozed, hidden (“Not interested”) or resting as worn out never come back this way. Only when even the store has too few does the fill pad with the nearest songs that don’t fit, so the music never stops. The log says so: heart-rate tempo: only N songs fit 142, padded with M nearest.
• Same scene. A song the fill adds from the store must belong to the music that is playing: the scene (language, genre and era) most of the current song and the songs around it share, or one of them when you are mixing scenes. A K-pop set never gets a British pop, Japanese anime or 1990s song this way, nor one whose scene Listen can’t tell. Eras count by decade: the 2010s fit the 2020s, the 1980s don’t. Songs you have played come before songs you have never heard. When too few songs fit, the fill takes fewer of them and keeps the DJ’s own songs, rather than reaching into another scene. The log line: heart-rate tempo: 9 fit 146, 31 rejected (other scene 20, other era 3, unknown 8) [session scene ko · pop · 2020s …].
• AI DJ. The AI DJ is told that heart-rate mode is on and the tempo is a hard requirement. Every candidate is marked “tempo fits the heart rate” or “tempo does NOT fit the heart rate, avoid”.
• Why this song. Auto-DJ picks that fit read “Matches your tempo: 142 BPM” (see Why this song?).
• The forgotten-favourite slot is skipped while the mode is on, because an old favourite at another tempo would break the run.

Switch the mode off and the next fills are ordinary again. Tempo picks already in the queue stay.

Testing without a strap

LISTEN_HR_FAKE=70:180,150:300,90:300 listen replaces the sensor with a scripted source: steps of bpm:seconds, one reading per second, repeated. Demo mode (listen --demo) plays this rest, run and cool-down curve by default. The MCP tool set_heart_rate takes on and sample_bpm, which feeds one reading as if it came from the sensor. get_now_playing reports the mode as heart_rate: on, status, the last bpm, the smoothed rate, the target, the source, the remembered sensor, the number of reranks and what the last_fill took.

Sound

Listen plays through mpv, so most sound settings map directly to mpv features. This page covers the output device, gapless playback, volume levelling, ReplayGain, the equalizer and compressor, speed and pitch, fades, streaming quality and transcoding, extra mpv options, and the server jukebox.

Most of these settings are in Settings → Playback, in the sections Playback, Audio output, Volume levelling, ReplayGain, mpv, Equalizer, Headphone correction, Compressor and Transcoding. Output device, speed and pitch are also in the Player options popover (the sliders icon in the player bar).

Note: Equalizer, headphone correction, compressor, volume levelling, ReplayGain, speed, pitch and fades are applied by mpv on this computer. They have no effect while you cast to a device or use the server jukebox.

Output device

To choose where sound comes out:

• Settings → Playback → Audio output → Audio device, then Refresh if the device is not listed; or
• right-click the speaker icon in the player bar; or
• use Audio device in the Player options popover.

The first entry, System default, follows the operating system’s default device. The other entries are the devices mpv reports. If the list cannot be read, the error is shown under the row.

More output options in the same section:

Gapless playback

Settings → Playback → Playback → Gapless playback sets mpv’s gapless-audio:

• weak (default): gapless, except when the audio format changes between two songs.
• yes: always gapless.
• no: a short gap between songs.

Listen prepares the next song while the current one plays, so albums and playlists play without a break. Crossfading between songs is not available as a setting; the DJ transitions blend songs that the Auto-DJ or AI DJ picked, and albums stay gapless.

Track fades

Two settings in the Playback section smooth the start and end of songs:

• Fade songs in and out: each song fades in at its start and out at its end over this time. Range 0 to 10 s in steps of 0.5 s; default 1.5 s; 0 turns it off. The AI DJ lowers and raises the music at this speed too (at least 1 s).
• Fade on pause: fades out briefly when you pause and back in when you resume. On by default.

Volume levelling

Volume levelling plays every song equally loud, so a quiet ballad after a loud dance track needs no hand on the volume. It is on by default. Choose the level in Settings → Playback → Volume levelling → Level:

How loud a song is comes from the first of these that knows it:

1. the analysis of the song (its measured loudness),
2. YouTube’s own loudness value, for YouTube Music songs that are not analysed yet (Listen asks YouTube once per song),
3. the song’s ReplayGain tags,
4. nothing: the song plays unchanged.

Loud songs are turned down as far as needed; quiet songs are turned up by at most 6 dB, and a limiter at the end of the sound chain keeps boosted peaks below −1 dB, so nothing clips. Changing the level while a song plays glides to the new loudness instead of jumping. Get info on a song shows the gain it gets and where its loudness came from (row Volume levelling); the log names it too (levelling: <title> −4.2 dB from analysis).

While volume levelling is on, it replaces ReplayGain (it reads the ReplayGain tags itself), so the ReplayGain settings below only matter with Off.

ReplayGain

ReplayGain evens out the loudness of songs that carry ReplayGain tags. In Settings → Playback → ReplayGain:

Equalizer

The equalizer has twelve bands at 31.5, 63, 125, 250, 500 Hz and 1, 2, 3, 4, 6.3, 10 and 16 kHz, each from -12 to +12 dB in steps of 0.5 dB, plus a Pre (preamp) slider with the same range.

To use it:

1. Open Settings → Playback → Equalizer and switch Equalizer on.
2. Drag the sliders, or pick a preset under Presets.

The built-in presets are Acoustic, Bass Boost, Bass Cut, Classical, Electronic, Flat, Hip-Hop, Jazz, Loudness, Pop, Rock, Treble Boost, Treble Cut, V-Shape and Vocal Boost. Choosing a preset sets the bands and resets the preamp to 0.

To save your own preset, set the bands, type a name into Save current as… and press Save. A saved preset appears in the list after the built-in ones, can be deleted with Delete, and takes precedence over a built-in preset of the same name. Reset sets all bands and the preamp back to 0.

Headphone correction

Headphone correction bends your headphones’ sound toward a neutral target, using the measured profiles of AutoEq (MIT licence). About 6000 headphone models are built into Listen, one profile per model (measurements by oratory1990 first, then crinacle, then the other sources), so nothing is downloaded. The correction runs first in the sound chain, before the equalizer, so the equalizer stays your own taste on top of a neutral sound.

A profile belongs to an output, not to Listen as a whole:

1. Play through your headphones (connect them, or pick them as the Audio device).
2. Open Settings → Playback → Headphone correction. This output names the output that plays now.
3. Type the model into Find your headphones (for example WH-1000XM5 or HD 600; hyphens and case don’t matter) and pick it. When the output’s name already says which headphones it is (Bluetooth headphones usually do), Listen suggests the profile before you type.

From then on the profile is applied whenever that output plays, and taken off when another one does. With the audio device on Autoselect, Listen follows the system’s default output (on Linux: pactl get-default-sink, checked twice a second), so connecting Bluetooth headphones or plugging in a wired pair switches the profile within a second. While a DJ transition plays (from loading the next song until the blend has ended) the switch waits and then uses the output that plays at that moment; a transition that is only planned doesn’t hold it up.

On Android the same section is in Settings, above the Equalizer. The phone binds a profile to the output media plays on (Bluetooth, wired, USB or the speaker, by the device’s name), so the same headphones over Bluetooth and over a cable are two outputs, and a switch applies at once, also during a transition.

You can also paste the text of an AutoEq or Equalizer APO ParametricEQ.txt into the search box and choose Use pasted profile. Other outputs lists the profiles bound to outputs that don’t play now; Remove takes one away. Headphone correction (on by default) turns all of them off without forgetting them.

Every profile keeps its preamp, lowered further when a band boosts more than it leaves room for, so the correction itself never clips; volume levelling’s limiter comes after it as usual.

Compressor

The compressor evens out loud and quiet passages. It uses ffmpeg’s acompressor filter inside mpv. It runs after the equalizer.

Switch Compressor on in Settings → Playback → Compressor, then pick a preset (Broadcast, Default, Gentle, Heavy, Light, Limiter, Loud Master, Moderate) or set the values:

Your own compressor presets work like the equalizer presets: type a name, press Save.

Speed and pitch

Open the Player options popover (sliders icon in the player bar). Playback speed runs from 0.5x to 2x. Press 1x to reset. For songs that have been analysed, the readout also shows the resulting tempo, for example 1.25 x / 150.0 BPM.

By default Preserve pitch is on: the music gets faster or slower and keeps its pitch. Switch it off (in the popover or in Settings → Playback → Audio output) to let speed and pitch move together, like a record. Then a row of pitch buttons appears:

• -1st and +1st change the pitch by one semitone.
• With Microtonal pitch controls on (Settings → Playback → Audio output), -10ct and +10ct change it by ten cents.

The readout between the buttons shows the speed and the pitch shift, for example 1.12x +1.96st. Pitch steps are speed steps: a semitone is a speed change by the twelfth root of two, within the 0.5x to 2x limit.

Note: The speed controls are disabled while DJ transitions are possible, because the transitions change the songs’ speed to match their tempos. That is the case when DJ transitions is on and the Auto-DJ or the AI DJ is on, which is the default setup. To change the speed, switch DJ transitions off in Settings → Playback → DJ transitions & song analysis, or leave the Auto-DJ and AI DJ modes (for example choose Off). Speed and pitch have no effect while casting.

Streaming quality and transcoding

Streaming quality (Settings → Playback → Playback) limits the bit rate to save bandwidth:

On Navidrome the server converts the song to MP3 up to the chosen rate; YouTube Music picks a smaller audio format. Local files, downloaded songs and the copies used for DJ analysis stay original.

If you want control over the format, use the Transcoding section. It appears when you have at least one server that is not YouTube Music. Switch Transcode on to ask Navidrome or Jellyfin to convert songs while streaming. It replaces Streaming quality for those servers; YouTube Music keeps that setting. New values apply to songs that start from then on.

mpv: executable and extra options

The mpv section of Settings → Playback is for special cases:

• Executable path: the mpv program to run. Empty uses mpv from your PATH. On Windows the setup wizard and Settings → Advanced → Helper programs manage mpv for you.
• Extra parameters: extra mpv options, one per line, for example --audio-channels=stereo. A missing leading -- is added for you. See the mpv manual for options.
• Reload mpv: stops playback and starts mpv again with the path and parameters above. Changes to path and parameters need this step. The Player options popover has a Reload button too.

Wrong parameters can stop playback from working. Clear the box and reload to go back to the defaults.

Jukebox mode

Some Subsonic-style servers can play music through their own speakers, controlled by a client. If the server answers Listen’s jukebox request, an Audio player row appears at the top of Settings → Playback → Playback:

• mpv (this computer) is the default.
• Jukebox (the server plays) hands the queue, starting at the playing song, to the server. Listen then only controls it: play, pause, stop, seek and volume are sent to the server, and the position is polled every two seconds.

The server administrator has to switch the jukebox on first. Listen sends up to 100 songs of the playing song’s server at a time. Equalizer, compressor, ReplayGain, speed and the DJ features do not apply to the jukebox. If the server turns out to have no jukebox, Listen plays with mpv again and tells you.

Full-screen player and Now Playing

The full-screen player shows the cover large with the song details, and one panel next to it: the queue, similar songs, lyrics or the visualizer. This page also covers its settings, the idle auto-open and the Now Playing page.

Opening and closing

Open the full-screen player in any of these ways:

• Click the cover in the player bar.
• Press the Lyrics or Visualizer button in the player bar. They open the full-screen player on that tab.
• Use the hotkey Toggle full-screen player (see Hotkeys).
• Switch on Player bar opens full-screen player (Settings → General → Player bar) and click an empty part of the bar.
• Switch on the song/video switch for a YouTube Music song (Music videos); the video is shown here.

Close it with the Minimize button (the arrow at the top left), the same hotkey, or Esc.

When nothing is playing, the window says “Nothing is playing.”

What you see

The top-left corner has two buttons: Minimize and Configure (the gear, see below). The top-right corner has five tab buttons:

Click a tab to open its panel; click it again to close the panel, and the cover moves to the middle. One panel is open at a time.

On the left are the cover (or the music video) and, under it, the title, the artists, the album and badges with technical details such as the codec. The title and the artists are links. A long title scrolls like a marquee unless you chose wrapped titles. When a DJ picked the playing song, a line under the album says why (see Why this song?).

The background takes its colour from the cover and changes with each song.

The visualizer tab has an Expand visualizer button at its top right that fills the whole window with the visualizer, with the song name in a corner. Use Shrink visualizer or Esc to go back.

About this song

The About tab shows three to five short facts about the playing song (what the title and the lyrics mean, how it was made, its release and how it was received), in the app language. Gemini writes them with Google Search, using the AI DJ’s key and text model (see Gemini key); without a key the tab says so. Every fact carries links to the web pages it rests on, and a fact without such a link is left out. If nothing with a source is found, the tab says so instead of showing a card. Searched for links the searches Gemini made to Google.

Under the facts are the Credits (writer, composer, lyricist, arranger, producer, mixing, engineer) from MusicBrainz, with a link to the recording there. Listen uses the song’s MusicBrainz recording id when your server has it, and otherwise searches MusicBrainz by title and artist. Many recordings, K-pop especially, have no credits there yet; then this part is missing.

The card is fetched when the tab is open (and again when the song changes while it is open), then kept for 30 days per song and language. Look it up again fetches a fresh one. One card costs up to three Gemini requests: when Gemini’s answer comes back without source links, Listen asks again.

In a narrow window (768 px or less) Listen uses a phone-style layout instead: a header, the cover, the details, a progress bar and the transport buttons, and a bottom row with shuffle, repeat, queue and lyrics. The queue and the lyrics replace the cover while they are open.

Settings of the full-screen player

There are two places:

1. Settings → General → Full-screen player has Full-screen auto-open timeout and Configure…. The same dialog opens from the gear inside the player.
2. Configure opens the dialog Full-screen player. Changes apply live behind the dialog; press Done to close it.

The available badges are Codec, Bit rate, Bit depth, Sample rate, BPM, Year, Release year, Date, Release date, Release type, Genres, Disc number and Track number. A badge is skipped when the song has no data for it.

Auto-open

To open the full-screen player on its own, for example when the computer acts as a music display, set Full-screen auto-open timeout to a number of minutes (1 to 120). After that many minutes without a mouse move, click, scroll or key press, while a song is playing, the player opens. Press Esc to return. The default, 0, switches the feature off.

Now Playing page

The Now Playing page is the queue as a full-width page, with the same toolbar and tools as the side panel. It also shows the number of songs, the total time and the play-mode button. Open it by clicking the song title in the player bar. To add it to the sidebar, enable Now Playing in the list of items in Settings → General → Sidebar; it is hidden by default.

While the page is open, the side panel and drawer are not shown, since the page already shows the queue.

Lyrics

Listen shows the lyrics of the playing song, highlights the line being sung and, when the lyrics carry word timings, the word. It can search other providers by hand, translate lines, show Japanese readings and export lyrics to a file.

Where to see lyrics

• The Lyrics button in the player bar opens the full-screen player on its Lyrics tab.
• A lyrics panel in the right sidebar: switch on Lyrics panel in Settings → Playback → Player sidebar panels. It can sit under the queue, or share one panel with the visualizer (Combine lyrics and visualizer).

Lyrics that follow the song (“synchronized”) scroll along and light up the current line. Plain lyrics without timing are shown as static text. If no lyrics are found, the view says “No lyrics found for this song.”

Where lyrics come from

When a song starts, Listen looks for lyrics in this order:

1. A lyrics version you picked by hand for this song earlier (see Search).
2. The song’s own server: Navidrome and other OpenSubsonic servers, and YouTube Music, can provide lyrics themselves.
3. The online providers you enabled.

With Prefer local lyrics on (the default), the server’s or YouTube Music’s synchronized lyrics are used without asking any provider. Plain server lyrics give way to synchronized lyrics from a provider. With it off, a provider result wins whenever one is found.

The providers are asked one after the other in your order. The first that has synchronized lyrics for the song wins. If none has, the best plain-text match of the earliest provider is used. A result is only trusted if title and artist are close enough to the playing song.

Each lookup sends the song’s title, artist, album and length to the providers you enabled. Nothing is sent when Fetch lyrics is off. While DJ transitions mix songs, the next song’s lyrics are looked up ahead too, to find where its singing starts.

To change this, open Settings → Playback → Lyrics:

• Fetch lyrics turns the lookup on or off. It covers the server’s lyrics as well as the providers. With it off, Listen finds no lyrics, apart from versions you picked by hand.
• Lyric providers lists the four providers. Use the switch to enable one and the arrows to change the order.
• Prefer local lyrics, as described above.

The Show the provider and Show the match switches in the display settings add a line naming where the lyrics came from (and which song the provider matched).

Using the lyrics view

Under the lyrics are two rows of buttons:

Offset

The number between − and + is the shift in milliseconds for this song. The default for all songs is Lyric offset in Settings → Playback → Lyrics (-2000 to 2000 ms, default 0). A per-song change lasts for the current session.

Searching for other lyrics

If the automatic lookup picked the wrong song or no lyrics:

1. Press SEARCH. The title and artist of the playing song are filled in.
2. Change them if needed and press Enter or Search. Every enabled provider is asked at once.
3. Select a result to preview it. Results are sorted with synchronized ones first, and marked synchronized or unsynchronized.
4. Press Apply to use it. Listen remembers your choice for this song, also after a restart.

Export in this dialog saves the previewed result.

Display settings

DISPLAY (and the same rows at the end of Settings → Playback → Lyrics) sets:

Line lead time makes a line light up that many milliseconds before its time stamp, so you can read ahead. Lines in right-to-left scripts such as Arabic and Hebrew are aligned to the right.

Karaoke highlighting

When lyrics have word timings (enhanced LRC files, or NetEase’s word-by-word format), the words of the current line light up as they are sung. There is no setting for this; it happens whenever the lyrics contain word timings and are synchronized.

Japanese: romaji and furigana

Two optional extras help with Japanese lyrics:

• Romaji shows the line in Latin letters under it. Kana are converted directly; kanji are read through the built-in dictionary when your build has one.
• Furigana shows the reading of the kanji above them. It needs the Japanese dictionary that normal builds include. If your build lacks it, the setting says so and stays off.

Both are off by default. Chinese text without kana is left alone.

Translation

There are three kinds of translation:

1. NetEase translations. Switch on NetEase translations to fetch NetEase’s own translation along with the lyrics and show it under each line.

2. Online translation with your own key. Listen can send the lyrics to Microsoft Azure Translator or Google Cloud Translation. Set it up in Settings → Playback → Lyrics:

   1. Pick Translation provider: Microsoft Azure or Google Cloud.
   2. Paste your API key into Translation API key. You need your own account with that provider; Listen has no key of its own.
   3. Choose Translation language (31 languages, English by default).
   4. Press TRANSLATION in the lyrics view to translate the playing song. Turn on Automatic translation to translate every song’s lyrics as they load.

3. Gemini (the AI DJ’s key). Pick Gemini as Translation provider. It needs no key of its own: it uses the Gemini key you set up for the AI DJ and its text model. Only lines with non-Latin letters are sent, numbered, so the translation always lands under the right line and whole English lines (common in K-pop) stay as they are, with no translation under them. English words inside a Korean line are kept. There is no romanisation. Each song’s translation is cached per language, so opening the song again needs no request; new lyrics for the song (another version) are translated afresh.

The whole text of the lyrics goes to the provider you chose in one request, with your key, and nothing else. The key is stored in Listen’s configuration file, so treat that file as private (see Privacy and security). The provider may charge for usage under your account.

Word meanings (Korean)

When the lyrics contain Korean and the AI DJ has a Gemini key, the lyrics controls show WORDS. Press it and every Korean word becomes clickable; click one to see its dictionary form (골랐다는 → 고르다), part of speech and a short meaning that fits the song, in the app language (German or English). All words of a song are looked up in one Gemini request the first time and cached, so later clicks open at once. Press WORDS again to make the lines clickable for seeking again.

Lute. Enter your vocab-hub address under Settings → Playback → Lyrics → vocab-hub address (empty = off). The word dialog then shows whether Lute knows the word (known, learning with its level, ignored, or not in Lute yet). Listen only reads your Lute words and never adds or changes a term; add new words in Lute itself.

Known words. With the vocab-hub set, WORDS also colours the Korean words by their Lute status: new words in green, words you are learning in light green, known and ignored words in the normal text colour. Next to WORDS the controls show how many of the song’s sung words you know (95 % known; every time a word is sung counts, ignored words are left out). Listen looks a word up as written, by its dictionary form and with particles cut off (사람들은 → 사람); words that are still unknown then are asked from the hub one by one, which finds conjugated forms the way Lute does (보낼게요 → 보내다). The percentage is the hub’s own count of the song (the same number the Lute Coverage extension shows). Lute changes show up within five minutes.

Exporting lyrics

EXPORT opens a preview of the file Listen would write. For synchronized lyrics you can keep Synchronized (.lrc) on (with an Offset (ms) written into the file) or switch it off to get plain text. The file is saved to your Downloads folder as Artist - Title.lrc or .txt, and the dialog shows the exact name. Word timings and translations are kept in the .lrc file.

Visualizer and Milkdrop

Listen draws a live picture of the music. The built-in visualizer is a spectrum analyzer with the same options as Feishin’s (audioMotion). On Linux you can switch to Milkdrop, which draws animated presets through libprojectM.

Where it appears

• Full-screen player: the Visualizer tab. The Expand visualizer button there fills the whole window; Esc or Shrink visualizer goes back. See Full-screen player.
• Right sidebar: a strip under the queue. It is on by default. Turn it on or off with Visualizer panel in Settings → Playback → Player sidebar panels (or Visualizer in queue in the Player options popover). You can also combine it with the lyrics panel and change the panel order there.
• The player bar’s Visualizer button opens the full-screen player on the visualizer tab.

While the visualizer is not on screen, Listen does not capture or analyse audio.

What it listens to

The visualizer analyses the audio Listen itself plays. On Linux it records Listen’s own playback streams through PipeWire (pw-record and pw-dump must be installed, which they are with a standard PipeWire setup). Other programs and the AI DJ’s voice are not included, and the volume slider does not change the picture. On Windows it uses a loopback of the default output device, so it shows whatever that device plays, which includes other programs.

If the capture fails, the panel shows the reason instead of a picture. The visualizer shows nothing while you cast or use the server jukebox, because Listen’s own audio is silent then.

Spectrum options

Open Settings → Playback, find the Visualizer section and press Configure… next to Visualizer settings. The dialog Visualizer settings has the options below. Their names and ranges follow Feishin and audioMotion, and the dialog changes the picture live.

Presets. Select Preset picks a saved set of options. Four presets (Preset 1 to 4) come with Listen. To keep your own, type a name under Preset Name and press Save as Preset; Delete removes one of yours. Copy Configuration puts the current options on the clipboard as JSON and Paste Configuration applies options from the clipboard, so you can share setups with other Listen or Feishin users. Reset to default at the bottom restores the defaults (your saved presets stay).

General

Colors: Color Mode (Gradient, Bar-Index, Bar-Level), Gradient (built-in gradients and your own), and for dual layouts Gradient Left, Gradient Right and Split Gradient.

FFT: FFT Size (1024 to 32768; default 16384) and Smoothing (0 to 0.95).

Frequency range and scaling: Minimum Frequency (20 to 50 Hz), Maximum Frequency (8000 to 22050 Hz) and Frequency Scale (Log, Linear, Bark, Mel).

Sensitivity: Weighting Filter (None, A, B, C, D, Z), Minimum Decibels (-120 to -60), Maximum Decibels (-40 to 0), Linear Amplitude with Linear Boost, and Volume (input gain, 0 to 4).

Peak behavior: Show Peaks (bar modes) or Peak Line (graph mode), Fade Peaks, Gravity, Peak Fade Time (ms) and Peak Hold Time (ms).

Radial spectrum: Radial, and with it Radial Invert, Spin Speed (-3 to 3 rpm) and Radius.

Reflex: Reflex Ratio, Reflex Alpha, Reflex Brightness, Reflex Fit and Mirror (Left, Off, Right).

Miscellaneous: for bar modes LED Bars (with True LEDs), Alpha Bars, Lumi Bars, Outline Bars, Round Bars, and Low Resolution (mode 0) or ANSI Bands; and for all modes Show Scale X, Note Labels, Show Scale Y and Show FPS.

Custom gradients. Under Custom Gradients, press Add Custom Gradient, name it, choose Vertical or Horizontal, and add colours as #rrggbb values with Add Color. Copy and Paste Gradient move a gradient through the clipboard. Your gradients then appear in the gradient choices.

Milkdrop (Linux)

Milkdrop is the classic music-visualizer format. Listen draws .milk presets with projectM. It is available on Linux only. Listen does not include projectM or any presets, so you need two things:

1. libprojectM version 4 installed on your computer. Listen loads it when it starts; it is not needed to build or run Listen otherwise. Listen looks for libprojectM-4.so.4 in the system library paths, in /usr/lib64, and in /usr/local/lib64 and /usr/local/lib (where a build from source installs it).
2. Milkdrop presets (.milk files) in a folder. By default that is presets inside the milkdrop folder of Listen’s data folder (on Linux ~/.local/share/listen/milkdrop/presets). Subfolders up to eight levels deep are read, so you can unpack a preset pack there as it comes. A different folder can be set in the settings.

To use it:

1. Open Settings → Playback → Milkdrop. If libprojectM is missing, the row says “Milkdrop needs libprojectM 4” and the button stays disabled.
2. Set Visualizer type to Milkdrop. The queue strip and the full-screen visualizer now show Milkdrop.
3. Choose your folder in Preset folder (Browse…) and press Rescan after adding files. The row shows how many presets were found.

If the folder has no .milk files, the picture area says so and names the folder.

Milkdrop renders on a hidden OpenGL context at 960 by 540 pixels and scales the picture to the available space. It draws from the same audio capture as the spectrum.

Music videos

For YouTube Music songs, Listen can show the music video in the full-screen player while the audio keeps playing as usual. This page explains the song/video switch and its limits.

Note: YouTube Music support is unofficial. Listen is not affiliated with, endorsed by or sponsored by Google or YouTube, and the feature may stop working whenever YouTube changes something. You use it with your own account and at your own risk. Listen does not download YouTube Music songs or videos for offline use. See YouTube Music.

Switching between song and video

The switch appears in the player bar only while a YouTube Music song is playing. It is a small video-camera button among the right-hand buttons:

• Show video switches the video on.
• Show song (the same button, now highlighted) switches back to the cover.

The switch is off by default. Turning it on opens the full-screen player and shows the video in place of the cover. The switch stays on for the following songs until you turn it off. In a narrow window, the phone-style full-screen player has the same switch in its bottom row.

How it behaves

• The audio plays through the normal player. The video is a separate, silent picture, and the audio is the clock: the picture follows it, and if it drifts too far, it catches up by skipping ahead or restarting.
• When the song plays from your own server (see YouTube Music), the video still shows: it follows the server’s audio as the clock. If both files have been analysed (including the YouTube Music one), Listen lines the video up with the server’s file by its beats and first sound; otherwise it assumes both start together.
• Seeking, pausing, resuming and skipping to the next song move the video along.
• The video of the next song is prepared in advance when possible, so it starts quickly after a song change.
• The picture is rendered at 640 by 360 pixels and 30 frames per second, with black bars for other aspect ratios. This keeps the load low, and the picture is not saved anywhere.
• For a song that has a separate music-video version, Listen shows the video; otherwise it shows the song’s own video.
• If no video can be played, Listen shows a message (“No video: …”) and the cover stays.

Requirements and limits

• Listen starts a second copy of mpv for the picture, and needs yt-dlp (a separately installed program, see Installation) to find the stream, as it does for the audio. If YouTube Music playback fails, update yt-dlp first.
• The switch is not offered for songs from other servers.
• It is turned off automatically when you start casting, and not offered while you cast.
• The video is only drawn in the full-screen player, not in the small cover of the player bar.
• A video uses noticeably more processor power and network traffic than audio alone.

Internet radio

Listen plays the internet radio stations stored on your Navidrome or other OpenSubsonic server. You can create, edit and delete stations from the app.

Availability

The Radio page is offered when the server you are browsing supports internet radio stations. Navidrome and other OpenSubsonic servers do; Jellyfin, YouTube Music and local folders do not. The Radio item is in the sidebar by default; if it is missing, check the sidebar items in Settings → General → Sidebar.

The stations are kept on the server, not in Listen, so they follow you to every app and computer that uses the same server account.

Playing a station

1. Open Radio in the sidebar. Each station is a card with its name, stream address, home page address and, if the server has one, a picture.
2. Click a card to play it. The card is highlighted, and the current stream title (“Now playing: Artist - Title”) appears on it when the station sends one.
3. Click the playing station again, or press Stop in the player bar, to stop it.

While a station plays:

• The player bar shows the station and the stream title. Only Stop and Play / Pause are available. There is no next, previous or seek, because a stream has no tracks.
• Your queue is left untouched and waits. Press Play on a song or start something else to go back to music.
• Starting a station ends casting to a device; the station plays on this computer.
• If the stream fails, Listen shows a message with the station name and the reason.

Finding and sorting stations

The page header shows the number of stations. Use the search field to filter by name, the sort list to order by Name or ID and the arrow to reverse the order. The refresh button reloads the stations from the server.

Creating, editing and deleting stations

To add a station:

1. Press Create station.
2. Fill in Name and Stream URL. The address must start with http:// or https://.
3. Optionally add a Home page URL.
4. Press Create.

The pencil button on a card opens the same dialog to change the station (Save). The bin button deletes it after a confirmation; this cannot be undone. If you delete the station that is playing, it stops.

Tip: Use the direct stream address of the station (often ending in .mp3, .aac or .m3u8), not the address of its web page. The web page address belongs in Home page URL.

Casting to speakers and TVs

Listen can hand playback to a network speaker or TV that supports DLNA / UPnP (a “media renderer”). This page explains how devices are found, how to cast, how volume works and what does not work while you cast.

Turning it on

Casting is on by default. The switch is Cast to DLNA devices in Settings → Playback → Playback. When it is on, Listen searches your local network a few seconds after it starts, and again whenever you open the cast popover or press Refresh in it. When it is off, Listen sends no discovery messages and shows no cast button.

Discovery uses the standard SSDP multicast on the local network, so the device and the computer must be on the same network (not a guest network that isolates devices), and a firewall must let the device’s answers and its requests for the music through.

Casting a song

1. Look for the cast button (a screen with a wave) among the right-hand buttons of the player bar. It only appears once at least one device has been found.
2. Click it. The popover Cast to a device lists This computer and the devices found, with their model names.
3. Click a device. It shows “Connecting…” and then a check mark. A message says “Casting to” the device’s name.

If your device is not listed, make sure it is switched on and on the same network, then press Refresh.

If a song was playing, it continues on the device from the same position. If nothing played, the device gets the playing song when you press Play. The queue stays in Listen; the device plays the songs one after another as the queue advances. Pause, stop, seek, next and previous in the player bar control the device.

To go back, open the popover and choose This computer. A song that was playing continues here at the same position.

Volume

While you cast, the volume slider and the mute button in the player bar control the device’s volume. The speaker icon turns accent-coloured, the slider’s tooltip names the device and the mute button’s tooltip reads “Mute the device”. When you stop casting, the local volume comes back as it was. A device that offers no volume control keeps its own level.

How the music reaches the device

The device fetches each song itself. For a plain http:// address, Listen simply passes the address on. For local files, and for streams that use HTTPS or need request headers, Listen starts a small web server on your computer, bound to the network address that reaches the device. The device then loads the audio from your computer. Each song gets an unguessable address, and Listen never passes your account’s cookies on. The server stops when you stop casting.

The device shows the title, artist and album of the song.

What does not work while casting

Everything that depends on this computer’s audio engine is off:

• DJ transitions and the AI DJ’s voice are off. The Auto-DJ still adds songs.
• The equalizer, compressor, ReplayGain, playback speed, pitch and fades, because mpv, which applies them, rests while you cast. See Sound.
• The visualizer has no audio to show.
• The song/video switch for music videos is off and is switched off if it was on.
• Songs are loaded one by one, so there can be a short gap between songs instead of gapless playback.
• Whether a particular file plays depends on the device: renderers differ in the formats they support. If a device cannot play a song, Listen shows “could not play this song” with the reason.
• Starting an internet radio station ends casting; the station plays on this computer.

If the device stops answering (five failed checks in a row), Listen says it lost the connection and continues playing on this computer.

The cast popover also notes these limits while a device is in use.

Song analysis

Listen can listen to your songs once and remember what it heard: where the beats and bars are, how fast the song is, which key it is in, how loud and energetic it is and how it is built. The DJ transitions and the AI DJ use these measurements. This page explains what is measured, where the results are kept and how to control the background work.

Analysis is on by default for Navidrome (OpenSubsonic) songs. You can ignore it completely if you do not use the DJ features: it never changes your files and it only runs in the background.

What is measured

For every analysed song Listen stores:

• Beats and downbeats. The position of every beat and which beat starts a bar. This is what makes beat-matched blends possible.
• Tempo. Beats per minute, with a confidence value. If your server provides a BPM tag, Listen uses it only as a hint to decide between half and double tempo.
• Key. The musical key, shown in the Camelot notation used by DJs (for example 8A or 11B). Keys that are neighbours on the wheel sound good together.
• Sections. Intro, body, breakdown, build, drop and outro, counted in bars, plus phrase length (4, 8 or 16 bars).
• Energy. Loudness, bass level, brightness and how likely a lead vocal is, one value per bar. From these Listen derives an overall energy, danceability and brightness. It also finds how many bars at the start and end of a song have no lead vocal, because those are the best places to blend.
• Loudness. Integrated loudness and loudness range, and the first and last moment where the song is actually audible.
• Timbre. A short vector that describes the sound of the song, used to judge how similar two songs are.

Songs without a steady beat (ambient, live recordings, strong tempo drift) get no beat grid. They are still analysed, but they are joined with plain fades.

Songs longer than 30 minutes are skipped.

Which songs are analysed

Songs from sources that are not analysed are never beat-mixed. They play as usual.

The beat model

To find beats and downbeats Listen uses a small neural network called Beat This! (MIT licence, from the Johannes Kepler University Linz). The two model files are about 11 MB in total and are downloaded once, the first time analysis runs. They are checked against a fixed checksum and then stored in the models folder inside Listen’s cache folder (see Files and folders). Nothing else is downloaded and no song data is sent anywhere.

If the download fails (for example because you are offline), Listen falls back to a simpler built-in beat tracker and tries to download the model again the next time it starts. The built-in tracker is less accurate, especially above about 140 BPM.

The status line (see below) shows which one is in use: Beats: Beat This! or Beats: built-in tracker.

The singing-voice detector (optional)

Where the singing is decides where a DJ transition can start and end without talking over a sung line. Without extra files Listen estimates it from the sound (centred, tonal sound in the voice range that changes like syllables). That estimate is rough: synth leads and chants can look like a voice, and a quiet first verse can be missed. Synced lyrics, when there are any, correct it (see Transitions).

For songs without synced lyrics you can download a small neural network that listens for singing: the singing-voice detector of the DJustify research project (Hsu et al., 2026), trained on the Jamendo corpus. Its code is MIT licensed, but its weights are licensed CC BY-NC 4.0: free for non-commercial use only. That is why Listen does not ship it and you choose to download it: Settings → Playback → DJ transitions & song analysis → Singing-voice detector → Download. The file (2 MB) comes straight from the authors’ repository at a fixed version, is checked against a fixed checksum and is stored in the models folder of Listen’s data folder, so clearing caches doesn’t remove it. Remove deletes it again.

With the detector, every song analysed from then on gets its vocal curve and its instrumental intro and outro from the detector (it adds about a second per song). Songs that were analysed without it are analysed again in the background, Navidrome and local songs only: YouTube Music songs keep their analysis, because fetching them again would use up YouTube’s request budget. The status line says vocals: singing-voice detector or vocals: built-in heuristic; it switches as soon as Download or Remove finishes. On three songs with synced lyrics, the detector’s vocal curve agreed with the lyrics better than the estimate (correlation 0.73 against 0.55; the start of the singing within 3 s instead of 10 s).

How the work is scheduled

Analysis runs in a separate helper process with low priority, so it should not disturb playback. The helper stops by itself after 30 seconds without work and is started again when needed.

Songs are analysed in this order:

1. The song that is playing and the next one.
2. The rest of the queue (the next 12 songs).
3. YouTube Music only: when Auto-DJ or the AI DJ is on, songs similar to the current one, so the next pick can be ordered by flow (Navidrome songs are covered by step 4).
4. The whole Navidrome library, a little at a time in the background. This is the “crawl”. Listen lists your library first and then works through it.

Queue work always goes first, so a song you are about to hear is analysed before a song you might hear next month. Library work pauses while a DJ transition is running, so the mix gets all the processor time it needs.

A 3.5 minute song takes roughly 2 to 3 seconds on a current desktop processor. A library of 10,000 songs therefore needs several hours in the background. Songs are analysed only once: the results are kept, and if two computers share the same folder they split the work (see Sharing between computers).

If a later version of Listen improves the analysis, old results are used until the song has been analysed again, and the new analysis runs at low priority.

Battery

On a laptop that is running on battery, library analysis pauses. Work for the queue (and for YouTube Music DJ candidates) still runs, because a transition may depend on it. To also analyse the library on battery, turn on Also on battery.

Note: Detecting battery power works on Linux. On Windows the library crawl is not paused on battery.

Threads

Beat detection uses several processor threads. By default Listen uses a quarter of your cores (at least one). To change that, set threads in the [analysis] section of the settings file (see Files and folders). 0 means automatic; any other number is limited to the number of cores you have. The change takes effect after a restart. There is no switch for it in the settings window.

Settings

All switches are in Settings → Playback → DJ transitions & song analysis.

Below the first switches there is a status line, described next.

The status line

The grey text under YouTube Music songs tells you what is going on. It can contain:

• N songs analysed, and in brackets how many each computer contributed when a folder is shared.
• library N songs, the size of the library found so far, with (listing...) while the library is still being listed.
• N waiting, the number of songs in line.
• A reason for waiting in brackets: paused during a DJ transition, library analysis is off or paused on battery.
• Now: the song being analysed.
• Beats: the beat source, vocals: where the vocal curve comes from, and this machine: the name that identifies this computer in the shared folder.
• An error, for example when the analysis folder cannot be written.
• If you have a YouTube Music account: YouTube Music: analysed on demand (queue and DJ candidates) or YouTube Music: not analysed.

It shows Off. when Analyse songs is off and Starting… for a moment after start.

The analysis folder

By default the results are kept in a folder called analysis inside Listen’s data folder (see Files and folders). To use another folder, type its path into Analysis folder and press Save, or press Choose… and pick it. Leaving the field empty returns to the default. Changing the folder restarts the analysis; results in the old folder are not moved, so copy them over first if you want to keep them.

Inside the folder Listen creates v1/<computer name>/000001.jsonl, 000002.jsonl and so on. These are plain text files with one song per line, including the artist and title so you can recognise them. They contain only measurements, never audio.

Sharing the results between computers

Analysing a big library takes time, so it is worth doing only once. If you point Analysis folder on every computer at the same synced folder (for example a folder in Nextcloud, Syncthing or any other sync tool), then:

• every computer reads the results of all the others;
• every computer writes only into its own sub-folder, so two computers never write to the same file and sync conflicts are avoided;
• songs that another computer has already analysed are not analysed again;
• the status line shows how many songs each computer contributed.

Results are matched by song and file, not by server address, so it also works when the computers reach the same server under different addresses. If a song’s file is replaced on the server (for example re-encoded), it is analysed again.

Tip: Let the sync tool finish its first sync before you start Listen on the second computer, otherwise both computers analyse the same songs in the meantime.

YouTube Music songs

Note: YouTube Music support in Listen is unofficial and not affiliated with Google or YouTube. See YouTube Music. Listen does not download YouTube Music songs for offline use.

YouTube Music songs can be beat-mixed too, but they need a measurement like any other song. This is off by default. To turn it on:

1. Choose an analysis folder first (see above). The switch stays off while the folder is empty.
2. Turn on YouTube Music songs.

When a YouTube Music song is wanted, Listen fetches a temporary copy of the audio, measures it, and then keeps only the measurements. The audio itself is not saved as a library.

YouTube Music songs are analysed only on demand: the playing song, the queue and a limited number of candidates for the DJ (at most 20 per playing song). The whole YouTube Music library is never crawled, and requests to YouTube are limited on purpose. If a request is turned down, Listen tries again later. You use this at your own risk, like the rest of the YouTube Music support.

Turning analysis off

Turn off Analyse songs. Existing results stay in the folder and are used again if you turn it back on. Without analysis the Auto-DJ and AI DJ still work, but songs are never beat-matched; they follow each other with the normal gapless playback.

You can also read progress from scripts: the MCP tool get_analysis_status returns the same information as the status line.

DJ transitions

With DJ transitions on, Listen mixes songs into each other like a DJ instead of simply playing one after the other. It matches the beat, lines the songs up bar by bar, and moves the bass and the tempo so the change is hard to notice. This page explains what happens and what each setting does.

Transitions use the measurements described in Song analysis. Without analysed songs nothing is mixed.

When songs are mixed

A transition is made only when all of this is true:

• DJ transitions is on.
• Both songs come from Navidrome (OpenSubsonic) or YouTube Music (with analysis switched on for it). Jellyfin, local files and radio are never mixed.
• A DJ chose the songs: the Auto-DJ or the AI DJ added the next song, or you added it with Add to queue while a DJ is on and Mix queued songs is on.
• The two songs are not consecutive tracks of the same album (same disc, track numbers one apart). Albums stay gapless.
• Both songs have been analysed.

Songs you start yourself by playing an album or playlist always play gapless, with no mixing. If a mix cannot be prepared in time, or you skip, seek or pause during the lead-up, Listen simply falls back to gapless playback.

What a transition sounds like

Listen looks at both songs and picks the best way to join them. It prefers to start the blend on a phrase boundary, where the outgoing song is instrumental (or at least has no singer at the same time as the incoming song).

Lyrics show where the singing is

The song analysis guesses from the sound where a singer is, and it often hears a voice in a synth lead or a chant. Synced lyrics are much more exact: each line has a start time, and the gap to the next line shows where the singing stops. So while a song plays and while it is next, Listen looks up its synced lyrics the same way as for the lyrics view (the server’s lyrics first, then the lyric providers if Fetch lyrics is on) and uses them for the transition:

• Where the singing is. Bars without a sung line count as instrumental, even if the sound analysis thought otherwise. That finds the short vocal gaps that pop and K-pop songs have, such as rap breaks, dance breaks and post-chorus hooks, so more pairs get a real blend and fewer a filter-out.
• Where a line ends. In the last 40 % of a song, a mix may start right after a sung line when a gap follows, not only in the outro. A mix that would stop the outgoing song in the middle of a line is avoided.
• Where the chorus is. The block of lines that repeats most is the chorus. A blend that ends right where the next song’s singing or chorus starts is preferred, and the next song may skip part of its intro for it (at most within its first 40 % or 90 seconds).

Cutting a song short or skipping an intro costs the plan points for every second, so Listen only does it when the join is clearly better. Transitions may skip parts of songs (Settings → DJ transitions) limits this: Free (the default) allows it as described, Short allows at most 16 seconds on either side, and Never keeps every mix in the outgoing song’s outro and starts the next song at its first beat. Lyrics are not used when they do not fit the song: when they run past its end, or when the sound analysis hears singing mostly where the lyrics are silent, or the lyrics fit much better a few bars earlier or later (an offset, or the lyrics of another version). Plain (unsynced) lyrics are not used. A transition is planned at once with what is known; if the lyrics arrive later but well before the mix, it is planned again.

While both songs play, Listen keeps the overall loudness steady: the sum of the two follows a straight line from the level of the outgoing song just before the mix to the level of the next song just after it. It knows how loud each part of a song is from the song analysis, so a blend over a quiet outro is lifted a little (at most 3 dB) and two loud choruses together are turned down (at most 6 dB). With Volume levelling on, each song’s own gain is taken into account. Echo-outs and cuts have no overlap and are left as they are.

Before a transition is armed, Listen plays it through once on the song analysis (no audio is needed, and it takes well under a millisecond). It rejects the plan if the mix would fall more than 1.5 LU below the quieter song or rise more than 1.5 LU above the louder one. Because the analysis is a little rougher than the audio, a predicted drop already fails from 0.9 LU. It also rejects it if both singers would be clearly heard together for more than a second, or if the outgoing song would stop in the middle of a sung line (this last check is only made when synced lyrics show where the lines end). A rejected plan gives way to the next best option, and the plain fade comes last. If no option passes, the one with the smallest problem plays. Rejected plans are written to the log with the reason.

For a beat-matched blend the two songs must run at the same speed. Listen speeds one or both songs up or down by a few percent without changing the pitch. With Tempo ramps on, the speed glides smoothly during the blend and returns to the natural speed of the new song afterwards. With it off, the tempo is matched for the whole blend at once, which can be heard on large differences.

Songs whose tempo is double or half of the other (for example 70 and 140 BPM) are matched at that ratio instead of being sped up a lot.

The speeds are taken from the bars that actually overlap, not from each song’s average tempo. Many songs drift a little (a slower intro, a live drummer), and a speed set from the average would let the beats slide apart by tens of milliseconds during a long blend. When the incoming song speeds up or slows down inside the blend, its speed glides along with it so the beats stay together, also when one of the songs slows down and picks up again within the blend (the speed then follows a smooth curve, adjusted bar by bar). A mix point whose beats still wouldn’t line up is passed over for a better one, or the songs join with an echo-out or a cut.

Note: Tempo changes use the rubberband library inside mpv. If your mpv was built without it, Listen uses a different method, which works but can make the beat wobble slightly while a song is not at its natural speed.

Bridge songs

Some pairs a DJ picked do not join well: the tempos are too far apart to beat-match, the keys clash, or the two songs simply sound very different. A club DJ solves this with a bridge track: a record that sits between the two, keeps the feel of the first and leads towards the second, so each step stays small.

With Bridge songs on, Listen does the same with a song that has already been analysed:

1. When the next song is far from the current one (no beat-matched join, a tempo gap of more than 4 %, clashing keys, or a large difference in sound), Listen looks for a bridge among your analysed songs: first the ones the DJs were recently offered, then your listening history, then every other analysed YouTube Music song. Only a few songs have a mostly instrumental stretch at a tempo between the two, so the whole collection is searched. Songs in the queue and songs played this session are not used.
2. The bridge must be closer to both songs than they are to each other, and both joins, into the bridge and out of it, must be beat-matched blends. When the two songs could only be joined with an echo-out, a cut or a fade, a bridge that is no further from either song than they are from each other is enough: a beat-matched way through a third song is preferred to those.
3. The bridge must belong to the music the two songs are from: between two K-pop songs it is a Korean pop song, never an American rap record that merely blends well. When the two songs are from different scenes, the bridge comes from one of them. Listen knows a song’s scene from its Describe it tags (genre, country and language), the song’s own genres, the artist’s other songs, or a Korean or Japanese title; songs it can’t place are also compared by their sound (the Describe it audio embedding). The scene includes the era (the decade, from the tags, the release year, the artist’s other songs or the songs that sound closest): a bridge between two songs of the 2020s comes from the 2010s or the 2020s, never from the 1980s or 1990s. A song without a known era fits only when its language and genre both match. The same artist always fits, and so does an artist you have heard right next to one of the songs, when nothing else is known and both or neither have a known era. A song whose scene is unknown is not used when the two songs’ scenes are known: no bridge is better than a wrong one. Among the songs that fit, the closest scene is preferred.
4. Only a short part of the bridge plays: 24 bars (about 45 seconds at 125 BPM) that start on a phrase and have no singing where they are blended, usually an instrumental groove, a break or a long intro. Listen blends into it with a short blend of up to 8 bars, glides it back to its own tempo, lets it play alone for a few bars, and blends out of it into the next song.

The bridge shows in the queue with the tag Bridge. It does not count as played: it is not scrobbled and not added to the listening history. If its mix cannot be prepared, the bridge is removed and the two songs join as before; if nothing mixes out of it, the next song starts when its part ends.

How often to bridge sets the share of far-apart pairs that get a bridge, so it stays an occasional move rather than a pattern. It applies only to pairs that could still be blended directly; a pair that would otherwise get an echo-out, a cut or a fade tries a bridge every time.

Order by flow

When a DJ picks several songs, Order by flow arranges them so that each song follows from the one before: similar tempo, neighbouring keys and a sensible energy curve, and without repeating the same artist too soon. The Auto-DJ and the AI DJ both use this. Songs without analysis are placed by the server’s own similarity order.

Order for smooth mixing

The same idea works on a whole playlist or the queue. Play in smooth order (right-click a playlist), Order for smooth mixing (right-click a queue row, or the button in a playlist’s edit mode) put all analysed songs into an order where tempo, key, energy and sound change as little as possible from one song to the next, and the same artist does not play twice in a row. The first song stays first (in the queue: the playing song). Songs without analysis keep their order and go to the end. A playlist on the server only changes when you press Save and replace in edit mode.

The order is found in a few milliseconds even for a few hundred songs: Listen starts with the closest next song each time and then keeps reversing stretches and moving single songs while that makes the whole run smoother.

Settings

Everything is in Settings → Playback → DJ transitions & song analysis.

One more value has no switch in the window. Set it in the [mixing] section of the settings file (see Files and folders) or with the set_settings MCP tool:

Mixing with the AI DJ

The AI DJ knows how each candidate song would be mixed in after the current one, and it can talk over a blend. When a spoken break is planned over the end of a song or the start of the next one, Listen allows a longer blend to leave room for the voice, and it keeps the voice shorter than the instrumental intro so the host never talks over a singer.

Troubleshooting

• Songs are not mixed. Check that Analyse songs is on, that the songs have been analysed (see the status line), that Auto-DJ or the AI DJ is on, and that the songs come from Navidrome or YouTube Music. Consecutive tracks of an album are always gapless.
• Many echo-outs, few beat-matched blends. Raise Largest tempo change: songs whose tempos are too far apart are joined with an echo-out or a cut. Songs without a steady beat are faded.
• A song was skipped for mixing right after you started it. A mix needs about 5 seconds of lead time. Songs started late are played gapless.
• A song ended earlier than usual, or the next one started after its intro. The lyrics showed a cleaner place to mix (see Lyrics show where the singing is). listen --check-mix A B --lyrics-a A.lrc --lyrics-b B.lrc shows how a pair is planned with given lyrics.
• Why was this transition chosen? The log lists every plan that was rejected before it (rejected … loudness dip, vocals clash, cuts a sung line). listen --check-mix A B --render out.wav shows the same check for a pair and measures the rendered preview’s loudness hole and bump.
• Different tempo after the mix. That is the intended tempo ramp. If you dislike it, turn off Tempo ramps or lower Largest tempo change.

How the engine works internally is described in DJ transitions internals.

AI DJ

The AI DJ picks sets of songs from your library that fit the mood of the song you started it on, and talks between the sets like a radio host. It uses Google’s Gemini models with your own API key. This page explains how to set it up, what every option does and what is sent to Google. To get a key, see Creating a Gemini API key.

The AI DJ is optional and off by default. It replaces the Auto-DJ while it is on, and it works together with DJ transitions and song analysis.

Turn it on

1. Create a Gemini API key (instructions).
2. Open Settings → Playback → AI DJ.
3. Paste the key into Gemini API key and press Save. Listen plays a short sample of the current persona’s voice to check that the key works. The result appears in a status line below the options (for example “Late-Night works.”).
4. Switch Enabled on. If there is no key yet, Listen refuses and tells you to add one. You can also tick Turn on the AI DJ in the setup wizard.
5. Start any song and choose AI DJ with the play-mode button in the player bar.

The song you start from becomes the seed: the mood the DJ tries to keep. Songs you add to the queue yourself while the DJ is on steer it too. If you want a new mood, start another song and switch the DJ on again.

What it does

While the AI DJ is on, Listen plans one set at a time. When the last song of a set starts, it asks Gemini for the next set and a line to say. Gemini chooses the songs from a list of about 40 candidates taken from your music server: songs similar to the seed, some similar to the current song, songs similar to your latest manual picks and a few random ones. Songs that played this session, are in the queue or were picked recently are left out.

With the listening history on, up to 5 of the candidates come from it: songs from your heavy rotation of the last 30 days (not ones played today) and favourites you have not played for two months, the ones that flow best from the current song. Each candidate also tells the DJ what you know of it: how often you played it and when you last did, or that it is new to you (and whether its artist is). The DJ mixes familiar songs with new ones, and when it talks before a set that has a song new to you, it introduces one of them with a short line about it. It is told to state only facts it is sure of and otherwise to talk about the sound. “New to you” is only used once the history covers at least two weeks and 100 plays, so a fresh install does not call every song new. These tags go to Gemini with the song titles (see Privacy).

With every set the DJ also writes a short note per song (at most 80 characters) on why it fits right now. Hold the pointer over the AI tag of a song in the queue to read it; the note of the playing song is shown in the full-screen player.

The break is spoken with a voice model and placed at random where it fits:

• between songs, in the silence after the current song;
• over the end of the current song, which is turned down while the host talks;
• over the start of the first song of the new set;
• across the change, starting over the end of one song and finishing over the start of the next.

The music is turned down while the voice speaks and back up afterwards. Breaks are short, at most 10 to 20 seconds of speech.

Tell the DJ

While the AI DJ is on, the queue panel (and the Now Playing page) shows a Tell the DJ… box with quick requests under it: Calmer, More energy, More new songs, Only favourites, Focus, Korean only and No ballads. Click a chip to ask for it and click it again to take it back, or type your own request (“more 2010s girl groups”) and press Enter; typed requests show as chips with an × to remove them.

A new request takes effect at once: the songs the DJ queued that have not started yet are taken out and it plans a new set with the request. The song playing now plays on (a transition already planned into the next DJ song keeps that song, and the new set follows it), and songs you queued yourself stay; while some of those are still queued, the new set comes after them. In its next break the DJ briefly says it heard you. Asking for a request that is already active changes nothing and costs no Gemini request.

Requests stay active, also after a restart, until you remove them, and every later set follows them. Calmer and More energy exclude each other, and so do More new songs and Only favourites. With analysed songs the requests also narrow the candidate list before Gemini sees it: Calmer keeps only songs with less energy than the ones it replaced (More energy: more), even when that leaves just one or two for a shorter set; only when no candidate has less (more) energy it keeps the eight calmest (most energetic), No ballads drops slow, soft songs, Focus drops the loudest ones, Only favourites keeps songs you have played at least three times (and takes more of them from your history) and More new songs keeps mostly songs new to you. Korean only is left to the DJ, because titles don’t show the language reliably.

How it uses the analysis

If songs are analysed, the DJ knows more than titles. Each candidate is described with tempo, key and energy, plus a short conclusion of how it follows the current song (keys compatible or clashing, tempo close or a big jump, energy up or down), and the DJ is told how the mix engine would bring it in after the current song. The candidate list is ordered by how well the songs flow from the current one, so the DJ is offered songs that mix well. The DJ can also mention its mixes, and it keeps a talk-over shorter than the instrumental intro of the next song so that it never talks over a singer.

Without analysis the DJ still works; it then relies on the server’s own similarity and the server’s BPM tag.

Where it works

The AI DJ picks songs from the server that the seed song belongs to. Beat-matched transitions between the picks need analysis, which exists for Navidrome and (if switched on) YouTube Music songs. When a speech clip is planned, it is not used while you cast to a TV or speaker over DLNA; the lines are then shown as text.

Personas

A persona sets the character, tone and voice of the host. Pick one in Persona and press Preview to hear it. The preview is cached, so after the first time it costs nothing.

The voices are Gemini’s built-in voices. Two-host breaks are spoken in a single request.

Settings

All options are in Settings → Playback → AI DJ.

Models

Listen uses two Gemini models. They are chosen for the free tier:

• Text model, gemini-3.5-flash-lite: picks the songs and writes the lines.
• Voice model, one of:
  • Flash-Lite TTS (fast), gemini-3.8-flash-lite-tts, the default.
  • Flash TTS (best voice acting), gemini-3.8-flash-tts, with more expressive delivery.

The text model can also be changed in the [ai_dj] section of the settings file (text_model). Use a model name that your key can access.

Location and Pronunciation

Type a town or region into Location, for example Kiel or Kiel, Germany. The hosts will mention it occasionally. Text after a comma or bracket is only context; for Pronunciation, Listen uses the first part (the place name). If the voice says the name wrongly, write it the way it should sound in Pronunciation, for example Keel, and use Preview to test. The hint is passed to the voice model for lines that contain the place name.

Details for the DJ

A line of free text, for example Call me Sam. I love 90s R&B. No weather talk. It is sent to Gemini with every break, so keep it short and do not put anything in it that you do not want to send to Google.

Quotas and the text fallback

The free tier of the Gemini API has daily and per-minute limits, and the speech models have a small daily allowance. Listen sets no limit of its own: every break is voiced until Google says the quota is used up.

• Spoken breaks in the settings shows how many breaks were voiced today. A day is counted like Google counts it, resetting at midnight Pacific time.
• Talk after lets the DJ skip talking after some sets.
• The Preview counts as one spoken break the first time you play a persona with a model.
• When Google says the daily speech quota is used up, the DJ keeps picking songs and shows its lines as text on screen. It tries speech again after an hour. Saving a new key clears this state.
• If the limit is only per-minute, Listen waits briefly and tries once more.

If the text model fails or its limit is reached, similar songs fill in (as if the Auto-DJ were on) and a message tells you that the AI DJ is unavailable. Listen then waits before trying again, a little longer after each failure, up to an hour. A rejected key shows a warning that points you to Settings → AI DJ.

Playback never waits for the DJ: if the answer is late, the music simply continues.

If the player ever ends up idle while songs are still queued — a song that will not load, a break whose clip had nothing behind it — a check every five seconds starts the next queued song, so the music picks up again on its own instead of standing still until you press play.

Privacy and data sent to Google

Listen has no server of its own. Requests go from your computer straight to Google under your own key.

What is sent:

• Song titles and artists the DJ chooses from, plus year and up to two genres where known.
• Short analysis summaries (tempo, key, energy) and a description of how songs were mixed.
• Which songs you skipped and which you queued yourself.
• Your requests from Tell the DJ.
• The DJ’s own previous lines.
• Your Persona, Language, Location, Pronunciation and Details for the DJ.
• The lines to be spoken (to the voice model).
• Your API key, as a request header.

What is not sent: audio of your songs, your server address and sign-in, file names or paths, and the rest of your library.

Outside the EU, UK and Switzerland, Google may use free-tier requests to improve its products, and human reviewers may read them. With billing enabled on the key’s project, requests are not used that way. Details are in Google’s Gemini API terms, which require you to be 18 or older. The generated clips are stored briefly in Listen’s cache folder and removed when Listen starts the next time.

The key is kept in the system keyring. The environment variable LISTEN_GEMINI_API_KEY, if set, takes precedence over the saved key, which is handy for testing.

Troubleshooting

Creating a Gemini API key

The AI DJ talks to Google’s Gemini models and needs an API key from you. Listen ships no key and has no server of its own. This page walks you through creating a key for free, putting it into Listen and looking after it.

You need a Google account and you must be 18 or older, because Google’s Gemini API terms require it.

Note: Google changes the AI Studio website from time to time. Button names may differ slightly from the ones below.

Create the key

1. Open Google AI Studio, API keys and sign in with your Google account.
2. If this is your first visit, read and accept the terms.
3. Press Create API key.
4. Choose a Google Cloud project:
   • If you have never used Google Cloud, pick the option to create the key in a new project. AI Studio creates a project for you, and that is all you need.
   • If you already have projects, you can pick one from the list. Use a project that is only for this purpose if you can, so you can see its usage separately.
5. Copy the key. It usually starts with AIza, and newer keys can start with AQ.. Treat it like a password.

If AI Studio shows a “default project” or asks you to import one, import or create a project first. A key always belongs to a project.

The button is greyed out

If Create API key cannot be pressed:

• Make sure you have accepted the terms in AI Studio.
• Make sure you are signed in with a personal Google account. Accounts of schools and companies (Google Workspace) can have the Gemini API switched off by an administrator, and you may need to ask them or use a personal account.
• Accounts of people under 18 cannot use the Gemini API.
• The Gemini API is not offered in every country. If it is unavailable where you are, AI Studio says so.
• If no project is listed, create or import one first, then try again.
• Reload the page, or sign out and in again.

Free tier or billing

You do not need a credit card or any billing to use the AI DJ. The free tier has daily and per-minute limits that are enough for normal listening. The most limited part is the speech: only a small number of spoken breaks per day are included. When it runs out, the DJ shows its lines as text. See Quotas and the text fallback in AI DJ. Google decides the exact limits and may change them; AI Studio shows the current ones for your project.

Free-tier requests differ from paid ones in how Google handles your data. Outside the EU, UK and Switzerland, Google may use free-tier requests to improve its products and human reviewers may read them. Paid usage (billing enabled on the key’s project) is not used that way. The AI DJ sends song titles, artists, the DJ’s lines and your Details for the DJ, so decide whether you are comfortable with this. What is sent is listed on the AI DJ page.

If you enable billing to get higher limits:

1. In the Google Cloud console open Billing, then Budgets and alerts, and create a budget for the project with an amount you are comfortable with, for example 5 euros.
2. Add e-mail alerts at a few percentages of the budget.

A budget alert warns you, but it does not stop the spending by itself. The AI DJ uses small text and speech requests, so normal use costs little, but a key that someone else gets hold of can cost money.

Put the key into Listen

1. Open Settings → Playback → AI DJ.
2. Click into Gemini API key and paste the key.
3. Press Save (or Enter). Listen stores the key in your system keyring and plays a short voice sample to test it.
4. If the status line says that the persona works, switch Enabled on.

The key is never shown again; the field then shows dots. It is not written to the settings file.

Replace, rotate or remove the key

• Replace or rotate. Create a new key in AI Studio, paste it into Gemini API key and press Save. Then delete the old key in AI Studio. Saving a new key also clears a “quota used up” state, which is useful if the new key is on a different project.
• Remove. Clear the field and press Save with the field empty. Listen deletes the key from the keyring and switches the AI DJ off.
• Revoke at Google. Delete the key in AI Studio. Listen then shows a “key was rejected” warning until you save a working key.
• Restrict. In the Google Cloud console you can limit a key to the Generative Language API, which is the one Listen uses.

If your key leaks, for example because you posted a screenshot, delete it at once in AI Studio and create a new one.

Troubleshooting

• “The Gemini API key was rejected”. The key was typed or pasted incompletely, has been deleted, or is restricted to something else. Copy it again and save.
• A quota message. The free limits are used up. See AI DJ.
• No keyring on your system. The key cannot be stored permanently. On Linux you need a running secret service such as GNOME Keyring or KWallet. See Troubleshooting.
• Testing without the keyring. The environment variable LISTEN_GEMINI_API_KEY is used before the saved key.

Media keys and system controls

Listen tells your desktop what is playing and accepts commands back, so media keys, lock-screen style widgets and panel applets work without Listen having focus. On Linux this uses MPRIS; on Windows it uses the System Media Transport Controls (the media flyout).

Linux: MPRIS

Listen registers itself on the D-Bus session bus as an MPRIS media player named Listen. Anything that speaks MPRIS can show and control it: the KDE Plasma and GNOME media widgets, panel applets, playerctl, KDE Connect, and so on.

What the desktop sees:

• Title, artists, album, album artist, track number, length and the cover.
• Genre, disc number, BPM, comment, year, last played, play count and rating when the song has them.
• The current lyrics (synchronised lyrics as LRC text) in the xesam:asText field.
• Playback state, position, volume, shuffle and repeat (none, track, playlist).

What the desktop can do: play, pause, play/pause, stop, next, previous, seek (relative and absolute), set the volume, switch shuffle and repeat, and raise the Listen window. Listen cannot be quit over MPRIS, and it does not expose a track list.

The player appears as soon as Listen starts. If the session bus is not available, Listen logs a warning and carries on without it.

Windows: media flyout

On Windows, Listen publishes to the System Media Transport Controls. That gives you:

• The media flyout (volume popup) and the lock screen with title, artist, album and cover.
• Hardware media keys and keyboard media keys, and the media buttons on headsets and Bluetooth devices.
• Play, pause, next, previous, stop, seeking and the position slider. The fast-forward and rewind buttons jump 10 seconds; the position slider sets an exact position.

Listen keeps a hidden helper window for this, so the controls keep working while the main window is hidden in the tray.

Media keys

Global media keys through the portal (Linux)

Settings → Hotkeys → System-wide → Global media hotkeys (on by default) lets Listen register these keys with the desktop’s GlobalShortcuts portal:

Listen only registers these on desktops that do not already route the keys over MPRIS. On KDE Plasma, GNOME, Cinnamon and Budgie the setting has no effect, because binding the keys twice would make every press fire two times. Turn the setting off if you want only MPRIS to control Listen.

The portal treats the keys above as suggestions. The desktop has the final say, and may ask you to confirm or may bind a different key. The Hotkeys tab shows what the desktop actually assigned under “Active in the desktop”. To change a key the desktop already bound, open the desktop’s own settings (for example System Settings → Shortcuts → Listen).

If your desktop has no GlobalShortcuts portal, the Hotkeys tab shows “The desktop refused system-wide shortcuts” with the reason. MPRIS keeps working.

See Hotkeys for the other system-wide shortcuts.

Troubleshooting

• Media keys do nothing on Linux: check that another player is not grabbing them, and that your desktop supports MPRIS or the GlobalShortcuts portal.
• On Windows the flyout shows an old song: it updates when the song changes; pausing and resuming refreshes it.
• A key fires twice on a non-listed desktop: turn Global media hotkeys off and let MPRIS handle it.

Hotkeys

Listen has a hotkey editor with one row per action. Hotkeys work inside the Listen window; on Linux you can also make most playback actions work system-wide. Open Settings → Hotkeys.

Recording a hotkey

1. Open Settings → Hotkeys.
2. Click the field in the row of the action. It shows “Press keys…”.
3. Press the key combination you want. The field takes the first valid combination.
4. To cancel, press Esc. To remove a binding, click the cross at the end of the row.

Notes:

• Mod means Ctrl. Combinations can use Ctrl, Alt, Shift and the Super/Windows key plus one key.
• A field with a red border means the same combination is used by another action.
• Every action starts unbound except the defaults in the table below.

Actions

“Global” means the action can be made system-wide on Linux (see below). Actions marked “No” only work while the Listen window has focus.

Details:

• Skip backward and forward use the amounts from the player bar settings (5 and 10 seconds by default). The volume step is the volume wheel step from the same settings.
• Rating hotkeys do nothing for sources without ratings, such as YouTube Music.
• Hotkeys that act on a list (the “List:” actions) use the rows you selected in the list that is on screen. See Lists, selection and menus.
• Window hotkeys are ignored while the command palette is open.

System-wide shortcuts (Linux)

On Linux the editor has an extra checkbox at the end of each row for actions marked “Global”. Tick it (after you have bound a key) and Listen registers the shortcut with the desktop’s GlobalShortcuts portal, so it works from any window, including on Wayland. This is supported by KDE Plasma and GNOME, among others.

• The key you record is only a suggestion. The desktop owns the final choice and may show a confirmation dialog or pick another key. The System-wide section shows “Active in the desktop: …” with what was really bound.
• A global action no longer fires from inside the Listen window, only from the portal, so it never runs twice.
• To change a key the desktop has already bound, use the desktop’s shortcut settings (for example System Settings → Shortcuts → Listen).
• If the portal is missing or refuses, a red message at the top says so, and the actions fall back to working inside the window only.
• Global media hotkeys is the separate switch for the hardware media keys; see Media keys and system controls.
• Clearing a hotkey also removes its global flag.

Windows

Hotkeys work while the Listen window has focus. There are no system-wide shortcuts for the editor’s actions on Windows; use the hardware media keys, which work through the media flyout (see Media keys and system controls), or the tray menu.

Tray, window and notifications

This page covers how Listen behaves as a desktop window: the tray icon, closing and minimising, starting hidden, running only once, remembering its size, the title bar, keeping the computer awake, song-change notifications and scrobbling. Most of it is under Settings → Window; scrobbling is under Settings → General → Scrobble.

Tray icon

Tray icon (on by default) shows Listen in the system tray. On Linux this uses the StatusNotifierItem standard (KDE Plasma supports it; GNOME needs the AppIndicator extension). On Windows it is a normal notification-area icon.

Left-click the icon to show the window. Right-click for the menu:

• Play / Pause
• Next Track
• Previous Track
• Stop
• Open main window
• Quit

The tooltip shows the playing song. Quit from the tray ends Listen completely.

Turning Tray icon off hides the three options below.

Close, minimise and start hidden

These options appear when Tray icon is on. All are off by default.

Note: Close to tray and Minimize to tray hide the window on Linux. On Windows the tray icon and its menu work, but at the moment the close and minimise buttons behave normally there.

On Wayland, a hidden window is really closed and a fresh one is opened when you bring it back, because Wayland applications cannot hide or restore their own window. You will not notice this apart from a short flicker.

One instance

Only one Listen runs per user. Starting it a second time (from the launcher, a file manager or the command line) does not open a second player: the running one comes to the front and the new process exits. The --route option of the command line is handed over the same way to open a page in the running instance.

Window size and position

Listen remembers the size, position (where the system allows), maximised and full-screen state of the main window and restores them at the next start. It is saved shortly after you stop resizing or moving the window, and again when you close it.

If a saved position is off-screen (for example the monitor was unplugged), the window is moved back onto a display, and it is shrunk if it is bigger than the display. On Wayland, Listen cannot read or set the position, so only the size and the maximised/full-screen flags are restored. The default size is 1600 by 950.

Title bar

Window bar style chooses how the top of the window looks:

The change applies immediately. Track info in window title (on by default) puts the playing song in the title, as “(3 / 40) Song - Artist - Listen”; a paused song starts with “Paused”. With it off, the title is just “Listen”. In private mode the title ends with “(Private mode)”.

Keep the computer awake

Two switches stop the computer from sleeping while music plays:

• Prevent display sleep while playing: keeps the screen on, and the system awake.
• Prevent system sleep while playing: stops the system from suspending; the screen may still turn off. This switch is on and locked while the display switch is on, because that already covers it.

Listen holds the lock only while a song is playing and releases it when you pause or stop. On Linux it uses the desktop’s Inhibit portal; if the portal is missing, a warning appears in the log and nothing is held. Both are off by default.

Song change notifications

Settings → General → Scrobble → Song change notifications (off by default) shows a desktop notification when the song changes, with the title, artists, album and the cover as the icon. The notification is silent. Skipping through several songs quickly shows only the one you land on, after it has played for a second. Notifications use the freedesktop notification service, so they are available on Linux.

Scrobbling

Scrobbling reports your plays to the music server and, once connected, straight to Last.fm (see Last.fm). It is under Settings → General → Scrobble.

Skipping ahead inside a song does not count as listening, only the time actually played counts. When a song starts, Listen also tells the server “now playing”; the scrobble itself is sent once the threshold is reached.

What happens on each source:

• Navidrome and other OpenSubsonic servers: the server’s scrobble call (now playing, then submission). Navidrome forwards it to Last.fm or ListenBrainz if you linked an account in Navidrome.
• Jellyfin: a “now playing” session report, then the item is marked as played.
• YouTube Music: the play is added to your YouTube Music history (not for guest sessions).
• Local folders and radio: nothing is reported.

Last.fm

Listen can scrobble to Last.fm itself, for every source: YouTube Music, Navidrome, Jellyfin and local folders alike. It uses the same rule as above for when a play counts, and shows the song as “now playing” on your profile while it plays.

1. You need a Last.fm API account (free, made with your normal Last.fm login at last.fm/api/account/create). Under Settings → General → Scrobble → Last.fm, enter its API key and Shared secret.
2. Press Connect to Last.fm. Your browser opens Last.fm; allow access there. Listen notices it within a few seconds and shows Connected as your user name.
3. Disconnect forgets the sign-in. Scrobble to Last.fm pauses sending without signing out.

The shared secret and the sign-in are kept with your server passwords (keyring), not in the settings file.

One name per song. The same song is often spelled differently by different sources: “Ditto (Official Audio)” on YouTube Music, “Ditto” in your tags; “뉴진스 (NewJeans)” or “NewJeans”; “OMG - Single” or “OMG”; an artist’s Korean and international name. Last.fm would count each spelling as a track of its own. Before a play is sent, Listen asks Last.fm which spelling of the artist, the title and the album most people use, and sends that one: upload labels such as “(Official Audio)” or “[MV]” go, “ - Single“ and “ - EP“ go, and an artist’s other name is used when Last.fm itself ties the two together (same MusicBrainz id, or the artist’s Last.fm biography names the other). The album is the one Last.fm files the track under, so the same song gets the same album from every source. The answers are kept for 30 days in lastfm/lastfm-names.json in Listen’s data folder.

Offline. Plays go into lastfm/lastfm-queue.json first and are sent in batches of up to 50. Plays made offline or while Last.fm is down are sent later (Last.fm accepts plays up to 14 days old). A short bridge stretch of the DJ is never scrobbled, and nothing is sent in private mode.

If you scrobble to Last.fm from Listen, unlink Last.fm in Navidrome (user menu → Personal → Scrobble to Last.fm off); otherwise Navidrome songs arrive twice.

Nothing is scrobbled in private mode. Turn it on under Settings → Window → Private mode (or in the application menu). In private mode nothing is scrobbled, shown on Discord or saved to the local history, and the window title says so. It switches off again when Listen restarts.

Discord status

Listen can show what you are listening to as a Discord Rich Presence status. It is off by default and needs the Discord desktop app to be running on the same computer. The settings are under Settings → Window.

Turning it on

1. Start the Discord desktop app.
2. Open Settings → Window and switch on Discord Rich Presence.
3. Play a song. Your Discord profile shows it within a few seconds.

If Discord is not running, Listen cannot connect and tries again with the next update (Listen re-sends the status every 15 seconds). Nothing is shown in private mode.

Options

The status shows the song as the first line, the artists as the second, the album as the cover’s tooltip and, while playing, a progress timer. Lines are cut at 127 characters.

Link types

• Last.fm links the artist to its Last.fm page and the song and cover to the album and track pages.
• MusicBrainz links use the MusicBrainz ids your server stores for the song (track or recording id, and release id for the cover). Servers that do not provide ids give no link.
• MusicBrainz (Last.fm fallback) uses MusicBrainz where ids exist and Last.fm otherwise.

Covers

Discord can only load images from public web addresses, so Listen picks a cover in this order:

1. A YouTube Music song uses its public https thumbnail.
2. With Show server cover image on, a song from a server that is reachable from the internet over https (a public host name, not a local name or private address) uses the server’s cover. The link includes your server’s access token, so Discord and the people who see your status can in principle read it. Only switch this on for a server you are comfortable exposing that way.
3. With a Last.fm API key, the album cover is looked up on Last.fm (a free key from Last.fm’s API pages). Results are cached for the session.
4. Otherwise Listen’s logo is shown.

Covers from local folders are never sent.

Listen’s own Discord application

By default the status uses an application registered for Listen, so Discord shows the name “Listen” and Listen’s logo. If you prefer your own name and artwork, create an application in the Discord Developer Portal, upload an asset named icon (plus playing and paused if you want the small icons), and paste its application ID into Discord application ID.

Private mode

With Private mode on (Settings → Window → Private mode or the application menu), Listen clears the status and does not show anything on Discord until you turn it off again or restart Listen. Private mode also stops scrobbling and history; see Tray, window and notifications.

Remote control

Listen can serve a small web page that works as a remote control for your phone or another computer on your network. It is off by default. The settings are under Settings → Window → Remote control.

Turning it on

1. Open Settings → Window → Remote control.
2. Switch on Enable remote control server. The row then shows “Running: open http://…:4333 on the phone”. If it cannot start (for example the port is taken), it shows “Not running” and the reason.
3. On the phone, open that address in a browser, replacing localhost with this computer’s address on your network, for example http://192.168.1.20:4333.
4. Optionally use the browser’s “Add to Home Screen” to install the page like an app.

Settings

Leave both username and password empty for no sign-in. If you set either, the browser asks for a login (HTTP basic authentication) before it shows the page.

What the page can do

The page has six tabs:

The star rating only appears for songs from a server that supports ratings. The page updates live over a WebSocket and reconnects on its own if the connection drops. Its message format is compatible with the Feishin remote.

Security

• The page and the connection use plain HTTP and WebSocket, without encryption. A basic-auth password is therefore visible to anyone who can watch your network traffic. Use the remote only on a network you trust, or keep the address at 127.0.0.1 and reach it through your own secure tunnel.
• With an empty username and password and an address other than 127.0.0.1, Listen shows a red warning: “Anyone in your network can control Listen. Set a username and password.”
• The page only receives what it needs: the song’s details and the cover, which Listen serves itself at /cover. Your music server’s address, login and tokens never leave Listen.
• Do not forward the port to the internet.
• Some systems ask you to allow Listen through the firewall the first time the server listens on a network address.

To use Listen from an AI assistant rather than a phone, see MCP server.

Continue on another device

With your own listen-server set up (Settings, Advanced, Listening history: the listen-server address and token), Listen on your computers and on the Android app knows what the others play.

• While another device plays, a strip above the player bar shows it: Playing on Phone: song · artist. Play here moves the music to this computer.
• Play on a device where nothing plays continues what another device plays, or what it played until a few minutes ago (10 minutes), at the same spot, with its queue.
• Connecting headphones (or any new audio output) to a device where nothing plays does the same when another device plays or stopped in the last 3 minutes. Take your Bluetooth headphones from the computer to the phone and the song goes along.

The device that played pauses and says where the music went. Songs that can’t play on the new device (a local folder only that device has) are left out of the queue; if the current song is one of them, nothing moves and Play plays this device’s own queue.

Turn it off with Continue on other devices in Settings, Advanced, Listening history. The wire format is in docs/handoff.md in the source repository.

MCP server

Listen has a built-in Model Context Protocol (MCP) server. It lets an AI assistant that supports MCP, such as Claude Code or Claude Desktop, play music, manage the queue and playlists, change the AI DJ and adjust settings for you. The server runs inside Listen on your own computer; nothing is hosted elsewhere. It is off by default.

Turning it on

1. Open Settings → Window → MCP server.
2. Switch on Enable MCP server. The row then shows “Running at http://127.0.0.1:4334/mcp”.
3. Listen creates an access token the first time it is needed and keeps it in the system keyring.

If the server cannot start, for example because the port is in use, the row shows “Not running” with the reason. Pick another port and press Enter.

Connecting a client

Every request must carry the header Authorization: Bearer <token>. The endpoint is http://127.0.0.1:4334/mcp (use your port; for another computer use this computer’s address instead of 127.0.0.1).

Claude Code

Press Copy command and run it in a terminal, or type it yourself:

claude mcp add --transport http listen http://127.0.0.1:4334/mcp --header "Authorization: Bearer <token>"

Start a new Claude Code session afterwards. The tools appear as listen.

Claude Desktop and other clients

Clients that support remote (HTTP) MCP servers take the URL and the header. Press Copy token to get the token.

Clients that only speak stdio can use a bridge such as mcp-remote. For Claude Desktop, add this to its claude_desktop_config.json, with your own token:

{
  "mcpServers": {
    "listen": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:4334/mcp",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

This needs Node.js (for npx). Restart the client afterwards.

What the server speaks

Streamable HTTP with JSON answers. Only POST /mcp is offered: there are no sessions and no server-sent event stream, so a GET gets “405 Method Not Allowed”. It understands the protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05. Up to 16 clients can be connected at once.

What an assistant can do

The complete list with every argument is in MCP tools.

Example prompts

• “What is playing right now, and what is next in the queue?”
• “Search for albums by Radiohead and play the newest one.”
• “Make a playlist called Sunday Morning with ten calm songs from my library.”
• “Add the songs from this album to my playlist Road Trip.”
• “Lower the volume to 30 percent and stop the music in 45 minutes.”
• “Turn on the AI DJ with the evening persona and set the language to German.”
• “Switch the gapless setting to yes.”
• “Remove everything after the current song from the queue.”

The assistant first searches, which returns references to songs, albums and so on, and then passes those references to the next tool. You do not need to know them.

Security

• Only programs on this computer can connect, unless you switch on Allow other computers. Even then every request needs the token. Listen shows a red warning while the server is open to the network.
• Web pages in your browser cannot talk to the server: requests that come from a web page on another site (an Origin that is not localhost) are refused.
• Whatever has the token can control Listen fully: change settings, edit or delete playlists on your servers, and use your Gemini quota through the AI DJ. Treat the token like a password and do not paste it into shared places.
• No tool ever returns a password, cookie, API key or the token. get_settings leaves them out, and get_ai_dj only says whether a Gemini key is stored.
• The connection is plain HTTP. On your own computer that is fine; over a network, anyone who can see the traffic can read the token. Prefer keeping Allow other computers off and using an SSH tunnel or similar if you need access from elsewhere.
• Destructive tools (clear_queue, delete_playlist) run without asking Listen’s confirmation dialog. Most MCP clients ask you before they run a tool; keep that on for these.
• New token immediately disconnects every client. Update the token in each client afterwards.

Themes and colours

This page explains how to change the look of Listen: the theme, light and dark mode, the accent colour, fonts, zoom and a few related options. All of them are on the Settings > General tab, in the Appearance and Application sections. To make your own theme, see Custom themes.

Choosing a theme

Listen ships with 32 themes plus six desktop presets, and it can load your own. Which picker you see depends on Follow system theme:

• Follow system theme on (the default): you choose a Dark theme and a Light theme. Listen uses the one that matches the desktop’s light or dark setting and switches when the desktop does. The defaults are Tokyo Night (dark) and Default Light (light).
• Follow system theme off: you choose one Theme that is always used. The default is Default Dark.

Every picker lists the same themes: the built-in ones, the desktop presets, and your own themes with “(custom)” after their name.

Built-in themes

The set is the same as in Feishin, which Listen’s interface is modelled on.

Following the desktop theme

On Linux, Follow desktop theme (on by default) makes Listen use the colours of your desktop instead of a built-in theme. It reads the KDE colour scheme (kdeglobals, including the accent colour) and follows changes live, usually within a second. When it is on, it takes precedence over the theme choices below it. The row’s description tells you what Listen found. If no desktop colours can be found, Listen uses the theme you picked.

The six presets named “(desktop)” in the pickers (Tokyo Night, Catppuccin Mocha, Gruvbox Dark, Nord, Rosé Pine, Dracula) are hand-tuned palettes. Listen selects one of them automatically when a compatible theme-switcher script on your desktop announces it.

This row does not exist on Windows. There, use Follow system theme.

Accent colour and shades

The accent colour is used for the primary buttons, active items and highlights.

• Use the theme’s accent colour: when on, each theme keeps its own accent. When off (the default), your accent replaces the theme’s.
• Accent colour: pick one of five swatches, or type any rgb(r, g, b) or #rrggbb value in the field. The default is rgb(53, 116, 252). The field and swatches are disabled while the previous option is on.
• Use the theme’s primary shade: when on (the default), buttons and links use the shade the theme prescribes.
• Primary shade: when the previous option is off, a slider from 0 (lightest) to 9 (darkest) picks which shade of the accent colour buttons and links use. The default is 6.

Fonts

The default is the built-in Inter.

Zoom

Zoom scales the whole interface from 50 % to 300 % in steps of 5 %. The default is 100 %. The change applies when you let go of the slider. The - and + buttons step by 5, Reset returns to 100 %. The zoom hotkeys (see Hotkeys) change the same value.

Backgrounds, covers and scrolling

Where the values are stored

All of these are stored under settings.appearance in config.toml. See the settings reference for every key.

Custom themes

You can add your own colour themes as small text files, and change colours, corner radii, spacing and font sizes of any theme with an override file. Listen reloads them while it runs.

The themes folder

Custom themes live in the themes folder inside Listen’s config folder (~/.config/listen/themes on Linux). To open it, go to Settings > General > Appearance and press Open folder on the Custom themes folder row. The row also shows how many custom themes were found and whether an override file is active.

Files can be JSON or TOML. Listen notices changes within about a second, so there is no need to restart: save the file and the theme picker and the interface update. Your themes appear in the theme pickers as “Name (custom)”.

A theme file

Create <name>.json or <name>.toml in the folder. The file name (without the extension) is the theme’s id.

{
  "name": "Sunset",
  "extends": "tokyoNight",
  "mode": "dark",
  "colors": {
    "background": "#1d1214",
    "surface": "rgb(42, 26, 29)",
    "primary": "#ff8844"
  }
}

The same theme in TOML:

name = "Sunset"
extends = "tokyoNight"
mode = "dark"

[colors]
background = "#1d1214"
surface = "rgb(42, 26, 29)"
primary = "#ff8844"

Colours

Keys are written in kebab-case:

background, background-alternate, foreground, foreground-muted, primary, state-error, state-info, state-success, state-warning, surface, surface-foreground

Values can be #rgb, #rrggbb, #rrggbbaa (the alpha part is ignored) or rgb(r, g, b). Colour names such as blue are not accepted.

The built-in theme ids are the names in the themes list written in camel case: defaultDark, catppuccinMocha, rosePineDawn, vscodeDarkPlus, solarizedLight and so on.

Note: Your accent colour setting still replaces primary unless Use the theme’s accent colour is on.

The override file

overrides.json or overrides.toml in the same folder is applied on top of whichever theme is active, including the desktop theme. Use it to tweak things without making a whole theme. Every key is optional.

[colors]            # the theme colours above, plus:
border = "#ffffff1a"
divider = "#ffffff0d"
nav-hover = "#2a2a3a"
icon-hover = "#26263a"
player-bar = "#101018"
primary-filled = "#3574fc"   # buttons, active navigation
primary-shade = "#2f63d6"    # links, selection outlines

[radius]            # pixels, 0 to 32: sm, md
sm = 3
md = 8

[spacing]           # pixels, 0 to 64: xs sm md lg xl
lg = 20

[font_size]         # pixels, 6 to 48: xs sm md lg xl
md = 15

Colours, radii, and the look of buttons, inputs and containers follow the override immediately. Spacing and font sizes apply to every screen.

When something is wrong

Problems are listed in red or grey under the Custom themes folder row in Settings:

• A file that is not valid JSON or TOML, is not an object, or has an unknown extends is listed as an error and that theme is skipped.
• A loop in extends, or a chain longer than 10, is an error.
• Two files with the same name (for example sunset.json and sunset.toml) are an error.
• An invalid colour value is dropped with a note, and the rest of the theme still loads. The same goes for unknown colour keys, an unknown mode, and out-of-range or non-numeric override values.

Fix the file and save it; the list updates on its own.

Languages

Listen’s interface is available in 17 languages. This page explains how to switch, how the AI DJ’s language fits in, and how to help.

Changing the interface language

Go to Settings > General > Application > Language and pick a language. The change applies after you restart Listen.

The choices are System default and these languages, each shown in its own language:

System default (the default) follows your computer’s language, read from the LC_ALL, LC_MESSAGES or LANG environment variable on Linux. If your language is not in the list, Listen uses English. Any Chinese locale maps to Simplified Chinese.

Text that has not been translated yet is shown in English.

The AI DJ’s language

The AI DJ has its own language setting, so the hosts can speak a different language from the one the interface uses. Find it under Settings > Playback > AI DJ > Language. The default, Same as the app, follows the interface language. Song titles stay in their own language.

The language of lyrics translation (Settings > Playback > Lyrics > Translation language) is a separate setting too.

Helping to translate

Translations are plain JSON files in the source repository, and corrections or new languages are welcome. See Translations for the file layout and how to send a change.

Where the setting is stored

settings.appearance.language holds the language code (for example de or zh-Hans); an empty value means System default. The AI DJ’s code is settings.ai_dj.language.

CD ripping

Listen can rip audio CDs on Linux. Put a disc in the drive and Listen makes a secure copy, tags it from MusicBrainz, adds cover art and files the album into your music folder, much like the auto-rip of MusicBee. This page covers the setup, every option under Settings → Advanced → CD ripping, and how to check a rip.

Note: CD ripping is available on Linux only. It uses the separately installed program whipper. On Windows the CD ripping section does not do anything.

What you get

• A secure rip with whipper (Test & Copy, checked against AccurateRip).
• Always FLAC at compression level 8.
• Tags and track names from MusicBrainz, cover art embedded in every file and saved as cover.jpg.
• ReplayGain tags for each track and for the album.
• Files named Album Artist/Album/NN Title.flac. Multi-disc releases use D-NN Title.flac.
• A notification when the album is done, and the disc is ejected.

Setup

1. Install the tools. On Fedora the Listen RPM already pulls them in. Elsewhere install whipper, flac and cdrdao with your package manager, for example:

   sudo dnf install whipper flac cdrdao
   

2. Run the check without a disc, or better with one in the drive:

   listen --check-cd
   

   It lists the tools, the drive and its read offset, the disc’s table of contents and MusicBrainz match, the music folder and your Navidrome server, and ends with “ready to rip” or the number of problems it found. See Checking a rip.

3. Open Settings → Advanced → CD ripping and set the Music folder.

If you plug in a USB drive later, Listen picks it up. The section shows the drive, its device (for example /dev/sr0) and the read offset it will use. Without a drive it says “No CD drive connected”.

The settings

Destination that is not available

If the music folder is a network share that is not mounted, the rip waits and tries again every 30 seconds. The panel says “Waiting for the music folder”. You can pick another folder with Choose folder… or press Retry. Listen first copies the finished album into a hidden .listen-incoming folder inside the destination and then renames it into place in one step, so a half-copied album never shows up in your library.

Read offset

Every CD drive reads audio shifted by a small number of samples. AccurateRip needs the right value to confirm that your copy matches other people’s. Listen takes the offset from, in this order:

1. The number you saved in Drive read offset.
2. whipper’s own configuration (~/.config/whipper/whipper.conf, written by whipper offset find).
3. The AccurateRip drive list built into Listen, matched by the drive’s model name.

The line under the setting shows which one is used, for example read offset +48 (AccurateRip).

If the drive is not in the list, the line says the offset is unknown and a rip stops with a message asking you to set it. Either type the offset into the field and press Save, or press Verify offset. Verify offset runs whipper’s offset search, which takes a few minutes and needs a well-known, commercially pressed CD in the drive. When it succeeds the result is stored in whipper’s configuration. The offset is a whole number between -3000 and 3000, with or without a plus sign. Clear the field and press Save to go back to automatic.

What happens when you insert a disc

The panel shows progress (“Ripping track 3 of 12”, “Tagging”, “Copying to the music folder…”) and ends with the folder and the AccurateRip result. While a rip runs you can press Cancel. Cancelling, or pulling the disc, leaves nothing in the music folder.

If some tracks could not be read perfectly, the panel asks “Publish the rest anyway?” with Publish anyway and Discard.

Rips to fix

If MusicBrainz does not know the disc, Listen still rips and files it as “Unknown Album (…)”, using CD-Text if the disc has it. Such discs are listed under Rips to fix (not on MusicBrainz) in the CD ripping section, newest first, with the album folder and a link: “Add the disc: …”. Open the link, add the release to MusicBrainz, then press Rip CD again to rip the disc with proper tags. The list shows the last 10.

Checking a rip

1. Run listen --check-cd with a disc inserted. It shows the track list, the disc ID, the MusicBrainz matches (best first, marked with an arrow), the cover it found and the exact folder and file name the album would get. It does not rip anything.
2. After a rip, open the album folder. You should see NN Title.flac files, cover.jpg and <Album>.log (whipper’s log). No .listen-incoming folder should remain. metaflac --list on a file shows the tags, MusicBrainz IDs, cover and ReplayGain values.
3. Logs: Listen’s own listen.log and one rip-<date>-<disc id>.log per rip are in the logs folder, ~/.local/share/listen/logs/. See Backup, logs and diagnostics.

For problems with the tools, drive or share, see Troubleshooting.

Importing from Feishin

Listen’s interface is modelled on Feishin, and it can read a Feishin settings export so you do not have to set everything up again. This page explains where to find the option, what is taken over and what is not.

How to import

1. Get a Feishin settings file: a JSON export of Feishin’s settings.
2. In Listen open Settings → Advanced and scroll to Import from Feishin.
3. Type or paste the path to the file in Feishin settings file, for example ~/Downloads/feishin-settings.json. A leading ~ is your home folder.
4. Press Import (or Enter).

Tip: Instead of typing the path you can drag the file into the Listen window while Settings is open. It is imported right away.

Listen shows “Feishin settings imported.” and applies the values at once. If the file cannot be read or is not a Feishin file, an error message tells you why, and nothing changes.

The import works the same on Linux and Windows, because it only reads the file you point to. Listen does not look for Feishin’s own configuration folder by itself, so you always give the path.

Note: The import changes the settings in place and does not ask for confirmation. If you want a way back, first make a copy with Export settings (see Backup, logs and diagnostics).

What is imported

Values that are missing from the file, or have a type Listen does not accept, keep their current value in Listen. Only what the file contains is applied.

What is not imported

• Servers and sign-ins. Add your servers in Listen as usual (see Connecting your music).
• Passwords. The remote-control password in the file is ignored.
• Hotkeys you did not set in Feishin. The bindings in the file replace your current ones; actions the file does not list keep Listen’s defaults.
• Settings that only exist in one app. Anything Feishin has and Listen does not, and the other way round, is left alone.

Note: If the file contains a lyrics translation API key, it is imported with the other lyrics settings and kept in Listen’s config.toml. Delete it in Settings if you do not want it there.

Listen’s own export is different

Settings → Advanced → Settings backup writes and reads Listen’s own format. If you give such a file to Import settings and it turns out to be a Feishin file, Listen tells you to use Import from Feishin instead. The other way round, the Feishin import expects Feishin’s layout and does not read Listen’s export.

See also Themes and colours for the Feishin themes that come with Listen.

Backup, logs and diagnostics

This page covers saving and restoring your settings, the log files, the diagnostics file you attach to a bug report, and the caches Listen keeps. All of it is in Settings → Advanced.

Settings export and import

Settings → Advanced → Settings backup

• Export settings writes all settings to a JSON file named listen-settings-<date>-<time>.json in your Downloads folder. If a file with that name exists, a number is added. A message shows the full path. Keys that look like secrets (password, token, cookie, API key and similar) are left out. The optional Last.fm key for Discord covers is the exception: it is a plain setting and is exported.
• Import settings reads such a file. Type or paste the path (for example ~/Downloads/listen-settings.json) and press Import.

Before anything changes, Listen checks every value and shows a confirmation: “N settings will replace your current ones. Servers and sign-ins are not touched.” If some values could not be used, the dialog lists the first six of them, each as setting.path: reason, and says they keep their current value. Typical reasons are a value of the wrong type, a setting that does not exist in this version (“unknown setting”), or a secret (“secrets are not imported”). Confirm to apply the rest, or cancel to leave everything as it is.

What is covered and what is not:

Importing works across machines and between Linux and Windows, so it is also the way to move your setup to a new computer: export, copy the file, import, then add your servers again.

If you give Listen a Feishin export here, it tells you to use Import from Feishin instead. See Importing from Feishin.

Note: Your servers and a few machine-specific values are kept in config.toml; see Files and folders if you want to back up the whole configuration by copying files.

Log files

Settings → Advanced → Logging

Listen writes a log while it runs, so you can find out why a song did not play.

The logs are in the logs folder of Listen’s data folder: ~/.local/share/listen/logs on Linux and %APPDATA%\Listen\data\logs on Windows. At each start the previous run is kept as listen.log.1 and mpv.log.1, so a crash does not erase its own log. The row Log level shows the exact folder.

Log level has two choices, and the change takes effect immediately without a restart:

• Debug (the default) records everything Listen’s own parts say. Use it when something does not work.
• Info records less detail and keeps listen.log smaller.

Cookies and stream URLs are not written to the logs, and obvious secrets are removed again when you export diagnostics.

If you start Listen from a terminal, it also prints log lines there. Set the environment variable RUST_LOG (for example RUST_LOG=debug) to change how much; see Command line.

Export diagnostics

Settings → Advanced → Logging → Export diagnostics

Press Export and Listen saves listen-diagnostics-<date>-<time>.zip in your Downloads folder. Attach it to a bug report; see Troubleshooting. It contains:

Before anything goes into the zip, Listen removes:

• values of keys such as password, token, secret, API key, cookie, authorization, signature, salt and credentials;
• the user name, e-mail and key fields in config.toml;
• the login part of URLs (https://user:pass@host becomes https://***@host);
• Authorization: Bearer … headers and common token formats (for example GitHub, Google API keys and Tailscale keys);
• sensitive query parameters such as t, s, u, p, key, sid and auth.

Server addresses, song and artist names and file paths in the logs are not removed, and neither is the optional Last.fm key of the Discord settings if you entered one. Open the zip and look through it before you share it, and send it only to people you trust with that information.

Caches

Settings → Advanced → Cache

Caches are copies of data Listen can fetch or compute again. Clearing them is always safe: your library, playlists and settings are not touched.

Each row shows how much space it uses. Clear asks for confirmation and then shows how many files and how much space were freed. Clear all clears the three disk caches at once, and Refresh sizes measures them again. After clearing the YouTube Music audio cache, songs you played before are fetched again when you next play them.

The cache folder is ~/.cache/listen on Linux and %LOCALAPPDATA%\Listen\cache on Windows. Other folders in it (the beat-detection model, AI DJ clips, downloaded updates, CD-rip work files) are managed by Listen itself and are not listed here. The full layout is in Files and folders.

Privacy and security

Listen has no server of its own. This page lists what leaves your computer, where it goes and why, how secrets are stored, and what you can turn off. The short version: no telemetry, no analytics and no account with the project. Listen talks only to the servers and services you set up, plus the ones listed below.

What goes where

Anything not in this table does not leave your computer. Music from your servers goes straight to your computer, not through anyone else.

You can turn off lyrics fetching, update checks, Discord, the AI DJ, song analysis and CD ripping individually in Settings.

What stays on your computer

• Listening history. Songs, server and time are saved in a file on your computer and never uploaded or shared. Switch Record listening history off or use Don’t record this session in Settings → Advanced → Listening history. You can export or delete the history there. See History, statistics and mixes.
• New from your artists. With Merge with other devices on, Home asks your own listen-server for the new releases it found. The server reads the YouTube Music pages of the artists you follow and play most, with the YouTube Music session the phone shared with it; nothing goes anywhere else. See Home.
• Describe it. The description you type on the search page goes to your own listen-server only. The listen-embed job (only if you run it) sends the artist and title of each analysed song to Gemini once for search tags, with your Gemini key, and fetches a 30-second clip of each song from YouTube Music or your Navidrome server; see Search.
• Song analysis results (tempo, key, sections) are stored locally, or in a folder you choose and sync yourself.
• Settings, queue and caches are plain files in Listen’s folders; see Files and folders.

Passwords, tokens and keys

Passwords, tokens and API keys are not stored in config.toml. They go to:

1. The system keyring: Secret Service (for example KDE Wallet or GNOME Keyring) on Linux, Windows Credential Manager on Windows.
2. A credentials file, credentials.toml in the config folder, when no keyring is available or it refuses a value. On Linux only your user can read it (permissions 0600); on Windows it lives in your user profile.

Settings → General → Servers → Password storage shows which is in use and lets you choose System keyring or File only. Switching moves the stored secrets. The file stores secrets in plain text, protected only by the permissions of your account, so prefer the keyring when you have one. If the keyring does not work, see Troubleshooting.

The Gemini key, the MCP token and the remote-control password are stored the same way. The optional Last.fm key and the lyrics translation key are plain settings in config.toml; keep that in mind before you share the file.

Logs and diagnostics

Log files stay on your computer. Cookies and stream URLs are not written to them. When you export diagnostics, Listen also removes passwords, tokens, cookies, keys and the login part of URLs. Server addresses and song names in the logs are not removed. Nothing is uploaded; you decide whom to send the zip to. Details: Backup, logs and diagnostics.

Letting other programs and devices in

Listen has two small servers, both off by default. Turn on only what you use.

Neither server returns passwords, cookies, API keys or the token itself. See Remote control and MCP server. Neither should be exposed to the internet.

Single instance and local sockets

Listen runs once per user. A second start talks to the first through a local socket (Linux: in $XDG_RUNTIME_DIR) or lock file (Windows) and exits. The audio player mpv is controlled through a private local socket. Neither is reachable from the network.

Reading browser cookies (YouTube Music)

To sign in to YouTube Music, Listen reads the cookies of youtube.com and music.youtube.com from the browser profile you pick, and only then. It stores which profile and channel to use, not the cookies. Because this looks unusual to some antivirus programs, they may warn about Listen on Windows; see Troubleshooting.

YouTube Music support is unofficial and not affiliated with Google or YouTube. You use your own account at your own risk.

Reporting a security problem

If you find a security issue, report it privately to the maintainers through the project’s GitHub page rather than in a public issue.

Troubleshooting

Answers to the problems people run into most. Each entry says what to check and, where it helps, which log to look at. The location of the logs is in Where are the logs? and the steps for a bug report are at the end.

YouTube Music songs stop playing

YouTube Music support is unofficial. It relies on the separately installed program yt-dlp to find the audio stream, and YouTube changes its site often enough that an old yt-dlp stops working. The most common cure is to update the helper programs:

• Windows: open Settings → Advanced → Updates → Helper programs and press Update. This updates mpv, yt-dlp and Deno with winget. Show lists what is installed.
• Linux: update yt-dlp with the way you installed it, for example sudo dnf upgrade yt-dlp, or pipx upgrade yt-dlp, or yt-dlp -U for a standalone copy. Check with yt-dlp --version.

Then try the song again. If it still fails:

• yt-dlp needs a JavaScript runtime for YouTube. Install Deno or Node.js (Linux: sudo dnf install nodejs). The message “yt-dlp … needs a JavaScript runtime” means it is missing.
• Run listen --check-youtube-music in a terminal. It signs in the way the app does, prints what Listen sees of your library (counts only) and tells you which step fails. See Command line.
• Look at listen.log (see below) for lines about yt-dlp.
• If the yt-dlp program lives in an unusual place, set the environment variable LISTEN_YTDLP to its full path.

YouTube may also restrict accounts it sees accessed by unofficial clients, or change things so that Listen has to be updated. See YouTube Music for what to expect.

YouTube Music sign-in says the browser is locked

On Windows a running browser keeps its cookie file locked. Close the browser completely (check the system tray and Task Manager for background processes) and pick it again in Listen. Listen reads the cookies when you select the browser, so you can start it again right afterwards.

Chrome, Edge or Brave on Windows cannot be used

Recent versions of Chrome, Edge and Brave on Windows protect their cookies with app-bound encryption, which only the browser itself can read. Listen then says “this browser protects its cookies with app-bound encryption (v20)”. Use Firefox instead, or choose Other ways to connect → cookies file and load a cookie export of music.youtube.com made with a browser extension. Listen’s login page also accepts such a file dropped onto it.

No sound, or “mpv” is missing

Listen plays through mpv.

• If you see “could not start mpv; is the mpv package installed?” or “The audio player (mpv) stopped unexpectedly”, install mpv. Linux: sudo dnf install mpv (the Fedora package of Listen already depends on it). Windows: the helper programs dialog installs it, or run winget install shinchiro.mpv.
• If mpv is installed somewhere unusual, enter its path in Settings → Playback → mpv → Executable path and press Reload. The environment variable LISTEN_MPV does the same for one run.
• Check the output device in Settings → Playback (the audio device list) and try System default.
• Extra parameters you or an imported Feishin file added can break mpv. Clear them and press Reload mpv.
• Look at mpv.log next to listen.log.

Windows SmartScreen or antivirus warns about Listen

The installer is not code-signed yet, so SmartScreen says the app is unrecognised. Click More info → Run anyway. Some antivirus programs also flag Listen because it can read a browser’s YouTube sign-in; it only reads the cookies of youtube.com and music.youtube.com, only when you pick a browser, and sends them only to YouTube. If your antivirus quarantines the program, restore it and add an exception. You can check the download against the SHA256SUMS file on the project’s releases page.

Keyring unavailable

Settings → General → Servers → Password storage says where your passwords are kept. If no Secret Service keyring is running (typical on minimal desktops and some window managers), Listen falls back to a private credentials.toml in its config folder and logs “keyring unavailable”. Everything keeps working. To avoid the warning or to decide yourself, install and start a keyring (KDE Wallet with the Secret Service interface, GNOME Keyring or KeePassXC), or choose File only. Switching moves your stored passwords. If a server keeps asking you to sign in again after a restart, the keyring probably refused to give the password back; choose File only to rule that out.

Global shortcuts and media keys on Linux

• Media keys normally work through MPRIS. KDE Plasma, GNOME, Cinnamon and Budgie send them to Listen themselves; Global media hotkeys is only needed on other desktops.
• Global hotkeys use the desktop’s shortcut portal (KDE Plasma and GNOME). The desktop has the last word: it may ask you to confirm the keys, may pick other keys than the ones you suggested, and shows them in its own shortcut settings. If it refuses, the Hotkeys page says “The desktop refused system-wide shortcuts” with the reason. Make sure the portal for your desktop (for example xdg-desktop-portal-kde) is installed and running, then restart Listen.
• On Wayland, apps cannot read or set their own window position, so Listen does not restore it and starts where the compositor puts it. Hiding to the tray closes the window and opens a new one when you bring it back. If you need X11 behaviour, start Listen with WINIT_UNIX_BACKEND=x11.
• In the tray, if your desktop has no tray (some GNOME setups need an extension), Listen starts with a window instead of hidden.

See Hotkeys and Media keys and system controls.

The visualizer shows nothing

On Linux the visualizer listens to Listen’s own audio through PipeWire (pw-record and pw-dump). Check that:

• PipeWire and its tools are installed (Fedora: pipewire-utils) and that pw-record --version works. With plain PulseAudio or ALSA there is nothing to capture.
• Something is playing. The bars follow Listen’s output only, not other programs.
• For the Milkdrop style, the projectM library is installed; without it only the bar styles are available. If Milkdrop shows a black picture, set LISTEN_MILKDROP_EGL to device, surfaceless or default to force one way of creating the graphics context.

For a detailed trace set LISTEN_VIZ_DEBUG=1 and read listen.log. See Visualizer and Milkdrop.

The AI DJ stopped talking or says the quota is used up

The AI DJ uses your own Gemini key, and the free tier allows only a limited number of spoken breaks per day. When Google reports the quota as used up, the DJ keeps choosing songs and shows its lines as text, and tries speech again within the hour. The AI DJ settings show “N of M spoken breaks left today”. The counter resets once a day, at midnight Pacific Time.

To get more speech, let the DJ talk less often (Talk after, Songs per set), lower Spoken breaks per day, or use a key from a project with billing enabled. If the DJ is unavailable altogether, check that the key is saved (press Save again, Listen checks it), that you are online, and that the key has not been deleted in Google AI Studio. listen --check-ai-dj runs two test rounds from a terminal. See AI DJ and Creating a Gemini API key.

Song analysis is slow or uses too much CPU

Analysis (tempo, key and sections for the DJ features) runs in the background at low priority. A large library takes hours the first time, and the results are kept, so it only happens once. To speed it up or slow it down, open the analysis settings in Settings → Playback:

• Whole library off: only the queue is analysed.
• Also on battery off (the default): analysis pauses when your laptop is unplugged.
• The number of analysis threads is not in the settings window. It is threads under [settings.analysis] in config.toml: 0 (the default) uses about a quarter of your processor cores, any other number sets the count, up to the number of cores. Restart Listen after changing it.
• Analysis folder: results are stored in Listen’s data folder unless you pick a (synced) folder. A folder on a slow network share slows things down.

The first run also downloads a small model file (about 11 MB). Without internet access Listen uses a simpler built-in tracker. You can also run listen --analyze-library --jobs 4 in a terminal to analyse the Navidrome library outside the app. See Song analysis.

CD ripping does not start

Run listen --check-cd. It names the missing tools (whipper, flac, metaflac, cd-paranoia, cdrdao), a drive that is not found, an unknown read offset, a music folder that is not mounted or not writable, and an unreachable Navidrome server. See CD ripping.

Lyrics, covers or a server do not load

• Self-signed certificate on your server: edit the server and turn on Ignore certificate errors, which applies to that server only.
• Wrong time or a proxy can also break secure connections.
• Press Clear all under Settings → Advanced → Cache to drop broken cached images.
• Look in listen.log for the failing address.

Listen is “already running”

Listen allows one copy per user. A second start brings the first window forward and exits. If the first one is hidden in the tray, use the tray icon. If you see no window and no tray icon, end the listen process in your task manager or with pkill listen and start again.

Where are the logs?

In the logs folder of Listen’s data folder:

Settings → Advanced → Logging shows the exact path. listen.log and mpv.log are rewritten at each start; the previous run is kept as listen.log.1 and mpv.log.1. More in Backup, logs and diagnostics.

How to report a bug

1. Reproduce the problem once with Settings → Advanced → Logging → Log level set to Debug (the default).
2. Right after it happened, open Settings → Advanced → Logging and press Export diagnostics. Do this before restarting Listen if you can, so the log of the failing run is the current one (a restart moves it to listen.log.1, which is also included).
3. Open the zip and read through it. Passwords, cookies and tokens are removed, but server addresses and song names are not.
4. Open an issue on the project’s GitHub page. Say what you did, what you expected and what happened, your Listen version (Settings → About), your operating system and desktop, and attach the zip.
5. For YouTube Music problems also include the output of listen --check-youtube-music and yt-dlp --version.

Settings

This page lists every setting on the Settings page, tab by tab and section by section, in the order they appear. For each row you get what it does, its default, and its key in config.toml.

How to read this page

• Open the Settings page from the sidebar. The tabs are General, Playback, Hotkeys, Window, Advanced and About. The search box at the top filters the rows of all tabs by name and description. Reset to default restores the settings after asking for confirmation.
• Settings are saved in config.toml in Listen’s config folder (see Files and folders). All keys below are written as paths from the top of that file; for example settings.ai_dj.location is the key location in the table [settings.ai_dj].
• Values written like "single" are the exact text stored in the file. Sliders are stored as plain numbers.
• Missing keys fall back to their defaults, so a hand-edited file only needs the keys you change. Edit the file while Listen is closed, or Listen may overwrite your change.
• Secrets (server passwords, the remote password, the MCP token, the Gemini API key) are kept in the system keyring or a restricted file, not in these keys.
• Rows marked Linux or Windows only are hidden on the other system. Some rows only appear when another option is on, or when the connected server supports the feature.

General

Servers

Lists your music sources with the buttons Switch (shown as Browsing for the active one), Rescan (local folders), Edit, Remove and Add server. See Connecting your music. Servers are stored in the [[servers]] tables, not under settings.

Scrobble