OpenTune is a terminal music player for Linux/Unix systems. Search YouTube for a song, choose a result using Vim-style keys, and listen without leaving the terminal.
It is deliberately small: OpenTune streams audio, with optional local downloads, and does not require a browser, YouTube account, or separate media library. Playback happens in a full-screen terminal UI (TUI).
This release adds persistent listening-history recommendations, a Suggestions home tab, continuously replenished queues, live search suggestions with cursor editing, playlist cut/copy/paste, clearer download/delete keybinds, and a one-time post-update support notice.
- Search YouTube from the command line:
opentune <music name> - Show several matching tracks with artist/channel and duration
- Play, pause, go to the next/previous track, seek, and loop a track
- Use Vim-like navigation (
h,j,k,l) as well as arrow keys - Create a continuously replenished related mix after you choose a song
- Show the upcoming mix in Queue and history-based recommendations in Suggestions
- Create persistent playlists in a right-side terminal pane
- Download tracks to a pinned local Downloads playlist
- Search and edit playlist contents without affecting the playback queue
- Mark contiguous songs with visual mode (
v) for bulk queue/playlist actions - Prefer downloaded local files automatically when a matching song is played
- Save listening history and use it to populate the Suggestions tab
- Cut, copy, and paste songs between playlists
- Show live music suggestions while editing a search query
- Loop an entire open playlist with
o - Display the playing title, elapsed time, total duration, and playback state
OpenTune coordinates two established command-line programs:
yt-dlpsearches YouTube and returns video title, channel, duration, and URL.- OpenTune shows those results in its terminal UI.
- When a track is selected,
mpvopens the YouTube URL and streams the best available audio format. - OpenTune controls
mpvthrough a private local socket, so pause, seek, loop, and progress updates work while the TUI remains open. - In the background, OpenTune asks YouTube for its radio/mix playlist seeded by the selected video, then filters alternate uploads of the same song before filling the queue. If YouTube does not expose a radio playlist, OpenTune falls back to other songs from the selected artist.
Search, first-time stream playback, and mix generation need an active internet
connection. d saves the highlighted song and Ctrl-d saves the currently
playing song locally for offline playback. Search prompts support arrow keys,
Ctrl-left/Ctrl-right, Home/End, and live suggestions.
Searches run in the background, so pane focus, tabs, playback, seeking, and
loop controls remain responsive while YouTube results load.
Install these before installing OpenTune:
- Python 3.10 or newer
mpv— audio playback and YouTube streamingyt-dlp— YouTube search metadataffmpeg— required only forCtrl-daudio downloads
Examples for common Linux distributions:
# Arch Linux
sudo pacman -S python mpv yt-dlp ffmpeg
# Debian / Ubuntu
sudo apt install python3 python3-pip mpv yt-dlp ffmpeg
# Fedora
sudo dnf install python3 python3-pip mpv yt-dlp ffmpegIf YouTube changes its site, updating yt-dlp is usually the first thing to try when search or playback stops working.
On current Arch Linux, do not use pip install --user for this project. Arch marks its system Python as externally managed (PEP 668), so pip correctly refuses to modify it. Choose one of the following isolated installation methods.
pipx installs Python applications into their own virtual environments while exposing their commands on your PATH. This is the best option when you want to run opentune from any directory.
# Install pipx once on Arch Linux
sudo pacman -S python-pipx
pipx ensurepath
# Open a new terminal, then install this checkout
cd /path/to/opentune
pipx install .Afterward, use it like any other command:
opentune "Daft Punk Get Lucky"
opentune --helpIf opentune is not found immediately after pipx ensurepath, restart the shell. pipx normally adds ~/.local/bin to your PATH.
pipx upgrade opentune checks the package's published source (usually PyPI). It cannot detect edits made only in this local Git checkout, even if the local version number changes. To install the current checkout after pulling or editing code, run this from the project directory:
pipx install --force .Or use the included shortcut:
make upgradeConfirm the installed release with:
opentune --versionIf a normal upgrade reports that OpenTune is already current but you suspect a stale or corrupted pip download, retry without pip's cache:
pipx upgrade opentune --pip-args="--no-cache-dir"This only refreshes the published PyPI package. For changes that exist only in
your local checkout, use pipx install --force . (or make upgrade) instead.
OpenTune follows semantic versioning: patch releases (for example 0.8.1 → 0.8.2) contain fixes, while minor releases add backwards-compatible features.
Use this when developing OpenTune or when you only need the command from this checkout:
cd /path/to/opentune
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
opentune "Daft Punk Get Lucky"Important: omit --user inside a virtual environment. The virtual environment already isolates the installation, and Python intentionally hides user site-packages from it.
To upgrade OpenTune inside the local virtual environment after pulling new changes:
cd /path/to/opentune
source .venv/bin/activate
python -m pip install --upgrade .
opentune --versionFor development, install the checkout in editable mode so source changes are available immediately:
python -m pip install --editable .If OpenTune was previously installed normally in this environment,
python -m pip install --upgrade . is sufficient. Do not use --user inside
a virtual environment.
While the environment is active, opentune works normally. After deactivate, either activate it again or run the executable explicitly:
.venv/bin/opentune "Daft Punk Get Lucky"Do not use --break-system-packages; it bypasses Arch's protection for the system Python and is unnecessary for OpenTune.
Installation and future upgrades from PyPI work from any directory:
pipx install opentune
pipx upgrade opentuneOpenTune v0.9.0 includes an installer hook for the short thank-you/support
message (direct legacy installs and verbose pip builds show it; standard pip may
hide build-hook output). On the first launch after a new release, the same
message appears in a floating modal;
press Esc to dismiss it. The notice is shown once per installed version.
Maintainers can follow the PyPI release guide to configure Trusted Publishing and publish releases.
For development or a one-off run from this checkout:
./bin/opentune "Daft Punk Get Lucky"Start OpenTune and search immediately:
opentune "Daft Punk Get Lucky"Words after opentune form the search query, so quotes are optional unless your shell needs them:
opentune Kendrick LamarStart with an empty player and search from inside the TUI instead:
opentuneUse the standard command help at any time:
opentune --help- Run
opentune <song or artist>. - A list of YouTube matches appears in the Results tab.
- Move with
j/kor↓/↑. - Press
Enterto start the highlighted result. - The title and time appear at the top of the screen.
- OpenTune prepares and continuously replenishes a YouTube radio-style mix in the background. Press
Tabto view it in the Queue tab, then again for Suggestions. - Press
qto quit.Esccancels prompts/visual mode; press it twice quickly in Queue or an open playlist to clear its find query.
| Key | Action |
|---|---|
j or ↓ |
Move selection down (wraps from bottom to top) |
k or ↑ |
Move selection up (wraps from top to bottom) |
g / G |
Jump to the top / bottom of the current list |
[ / ] |
Move to the previous / next item in the current Results search |
Ctrl-b / Ctrl-f |
Move half a page up / down |
Enter |
Play the selected result or queue item |
Space |
Pause or resume playback from any window |
h |
Play the previous track, if there is one |
l |
Play the next queued track |
H (Shift+h) |
Rewind 10 seconds |
L (Shift+l) |
Forward 10 seconds |
Ctrl-o |
Toggle looping of the current track from any window |
Tab |
Switch between Results, Queue, and Suggestions |
/ |
Open a search prompt from any window |
f (Queue tab) |
Find and highlight a song in the Queue without filtering it |
n / N (Queue tab) |
Jump to the next / previous match; status shows [current/total] |
Shift+h/l or Shift+Left/Right |
Rewind/forward 10 seconds from any window |
a |
Append the focused result/queue track to the Queue without playing it |
s (Queue tab) |
Shuffle only the temporary Queue; saved playlists are unchanged |
v |
Enter/leave visual selection; extend the selection with j/k |
d |
Download the highlighted result, queue item, suggestion, or playlist song |
D |
Delete selected queue/playlist songs or a playlist after confirmation |
c |
Clear the Queue after y/n/Enter confirmation |
u |
Undo the last queue deletion or clear |
Ctrl-r |
Redo the last undone queue deletion or clear |
pN |
Add the focused result/queue track to user playlist number N |
pcN |
Add the currently playing track to user playlist number N |
Ctrl-d |
Download the currently playing track (or focused playlist song if idle) |
x / y / z |
Cut / copy / paste selected songs in an open playlist |
P |
Toggle the Playlists pane |
Ctrl-h / Ctrl-l or Ctrl-Left/Right |
Cycle focus between panes (wraps) |
? |
Open/close the in-player key reference |
Esc in a prompt or visual mode |
Cancel the prompt or visual selection |
Esc twice in Queue |
Clear the active Queue find query |
Esc twice in an open playlist |
Clear the active playlist find query |
Esc in help |
Close the help overlay or the v0.9.0 update notice |
q |
Quit OpenTune (the only quit key) |
The Results tab contains the latest YouTube search. Each row shows its title, channel/uploader when available, and duration. Press Enter to play a result. Use [ and ] to move through the current search results without changing the playing track; h and l remain music navigation. Choosing a new search result replaces the current track and adds the former track to playback history, allowing h to go back. While typing in /, OpenTune requests live music suggestions; recent matching history entries are marked [history] and use fuzzy matching. Use Up/Down to choose a suggestion or Tab to complete it.
Selecting a search result starts a YouTube radio-style mix. OpenTune filters duplicate uploads, alternate versions of the selected song, and obvious non-music results, so the queue should contain different music tracks rather than the same title from several channels. The Queue tab shows the tracks waiting to play. You can:
- Press
lto start the next queued track. - Highlight a queued track and press
Enterto jump directly to it. - Press
aon a search result to append it without interrupting playback. - Press
Dto remove highlighted queue item(s) after ay/n/Enter confirmation, orcto clear the whole queue. - Press
uto undo the latest deletion/clear, orCtrl-rto redo it. - Press
fto find and highlight a queue song without changing the queue. - Press
n/Nto move to the next/previous match; matches wrap around and the status line reports their position as[current/total]. - Use
Tabto return to Results.
When the queue reaches its end, OpenTune requests another related batch and
continues playback automatically. Quitting with q stops replenishment.
The Suggestions tab contains recent unique songs from the persisted listening
history. Starting a song records it immediately in ~/Music/opentune/history.json;
the list is refreshed as playback continues and is available after restarting
OpenTune.
Undo and redo are intentionally limited to queue deletion and queue clearing. Playback, search, pause, seeking, looping, and adding tracks are not recorded in the undo history.
Press P to open or close the Playlists pane. It occupies about 40% of the
terminal width. When open, Ctrl-h/Ctrl-Left cycles focus left and
Ctrl-l/Ctrl-Right cycles focus right; focus wraps between the panes. The
pane stays open after starting a playlist track.
The pinned Downloads playlist has no user-playlist index. User-created
playlists are numbered from 1 in the visible list and remain in creation
order (with pinned user playlists grouped first). Playlist files are stored in:
~/Music/opentune/Playlists/
Downloaded audio files are stored in:
~/Music/opentune/Downloads/
| Key | Action |
|---|---|
j / k |
Move down/up through playlists |
Left / Right |
Leave / enter a playlist |
g / G |
Jump to the top / bottom of the playlist list |
Ctrl-b / Ctrl-f |
Move half a page up / down |
l |
Enter the focused playlist |
a |
Create a playlist; an empty name becomes My Playlist #N |
p |
Pin/unpin the focused playlist (Downloads is always pinned) |
r |
Rename the focused playlist (Downloads cannot be renamed) |
D |
Delete the focused playlist after confirmation (Downloads is protected) |
P |
Toggle the pane |
Ctrl-h / Ctrl-l or Ctrl-Left/Right |
Cycle focus between panes |
| Key | Action |
|---|---|
j / k |
Move through songs |
g / G |
Jump to the first / last song |
Ctrl-b / Ctrl-f |
Move half a page up / down |
v |
Enter/leave visual selection; extend the selection with j/k |
Enter |
Play the focused song and load the playlist into the temporary queue |
h |
Leave the current playlist and return to the playlist list |
a |
Append the focused song to the temporary Queue without playing it |
pN |
Add selected playlist song(s) to another user playlist N |
pcN |
Add the currently playing track to user playlist N |
f |
Find and highlight a playlist song by title or uploader (no filtering) |
n / N |
Jump to the next / previous match; status shows [current/total] |
d |
Download the focused song |
D (Shift+d) |
Permanently delete the focused song(s) after y/n/Enter confirmation |
x / y / z |
Cut / copy / paste selected songs into the open destination playlist |
o |
Toggle looping of the current playlist |
P |
Toggle the pane without closing the playlist |
The matching text is shown in a secondary color while the selected row keeps
the primary selection color. Press Esc twice quickly while a Queue or
playlist find query is active to clear the query. A single Esc leaves the
current list unchanged.
Playlist song deletion has no undo/redo. A deleted song must be added again
with pN from a main-window search result, queue item, or open playlist song.
Visual mode (v) makes j/k extend a contiguous selection. Press Esc to
cancel visual mode without changing anything. Actions such as
queue append/delete, playlist append, and playlist deletion apply to every
selected song. Press v again to leave visual mode.
Focus a search result or queue item in the main window, press p, then type its
user-playlist number. For example, p3 adds the focused track to user playlist
3. Inside an open playlist, p3 adds the selected playlist song(s) to user
playlist 3; use pc3 to add the currently playing track. Downloads is not a
numbered target and cannot receive songs through pN/pcN; it is populated
only by successful d/Ctrl-d downloads. User playlists store the YouTube URL and
metadata; they do not download the song.
Press d on a highlighted song, or Ctrl-d for the currently playing song
(and the focused playlist song when idle). OpenTune uses yt-dlp
and ffmpeg to save an MP3 under ~/Music/opentune/Downloads/ and adds it to
the pinned Downloads playlist. Deleting a Downloads entry after confirmation
also removes its local audio file permanently.
The a key creates playlists only when the Playlists pane is focused on the
playlist list. Inside an open playlist it appends the focused song to the
temporary Queue; in the main window it appends the focused result or queue item.
The queue is kept in memory for the current session only. It is cleared when OpenTune exits.
Ctrl-o loops the currently playing track from either the main window or the
Playlists window. The screen header displays LOOP while it is enabled. Turn
it off with Ctrl-o again; then, when a track ends, OpenTune advances to the
next item in the queue. In an open playlist, o loops the whole playlist and
shows PLOOP in the header; it starts the playlist again after its final song.
Ctrl-h/Ctrl-l (or Ctrl-Left/Right) cycles focus between panes when the
Playlists pane is open.
The user-level bin directory is likely not on PATH. Run:
export PATH="$HOME/.local/bin:$PATH"Then add it to ~/.zshrc or your shell's startup file as described above.
OpenTune checks for both commands at startup. Install the missing package with your distribution's package manager, then run OpenTune again.
-
Confirm that the internet connection and YouTube are reachable.
-
Update
yt-dlp; YouTube changes can require a newer version. -
Try the URL in
mpvdirectly to distinguish an OpenTune issue from ampv/yt-dlpissue:mpv --no-video "https://www.youtube.com/watch?v=VIDEO_ID"
OpenTune needs an interactive terminal with enough space for the player. Enlarge the terminal window and avoid running it through a non-interactive shell or redirected output.
opentune/
├── bin/opentune # launcher for running from this checkout
├── opentune/__main__.py # CLI, terminal UI, search, queue, and mpv control
├── tests/ # small automated checks
├── Makefile # install, local pipx upgrade, and test shortcuts
└── pyproject.toml # package metadata and installed `opentune` command
OpenTune currently provides persistent playlists and optional downloads. Lyrics, volume controls, and system media-key integration remain outside the current scope.
Copyright 2026 Rudraksh.
OpenTune is licensed under the Apache License 2.0. It includes an explicit patent grant; see NOTICE for the project attribution notice.