Search, download and play music from YouTube.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ralf Hersel 693dc21295 v0.31 4 months ago
img v0.31 4 months ago
.gitignore v0.30 4 months ago v0.31 4 months ago
youplay.desktop v0.27 8 months ago v0.31 4 months ago v0.27 8 months ago
youplay.svg v0.19 9 months ago

Logo Welcome to YouPlay

Do you love music, but hate restrictions?

With YouPlay you can search for whatever music song in your mind. It will list a number of matching songs. You can listen to it and YouPlay will download it as an mp3 file.

YouPlay in GUI-mode

YouPlay Screenshot GUI

YouPlay in CLI-mode

YouPlay Screenshot CLI


You can install YouPlay manually or as an AUR package. More package formats, e.g. Flatpak, are planned. You can install YouPlay to your system with the instructions described below:

Manual Installation

This installation method is still the prefered one, until an installable package is available. Run these commands in a terminal:

git clone
cd youplay

Than install these packages with the package manager of your GNU/Linux distribution:

mpv, libmpv1, ffmpeg, python3-pip

On Debian-based systems you can do this with one command:

sudo apt install mpv libmpv1 ffmpeg python3-pip

On Arch-based systems:

sudo pacman -S mpv ffmpeg python-pip

Now install the Python libraries python-mpv and youtube-dl with:

  • pip3 install --upgrade python-mpv

  • pip3 install --upgrade youtube-dl

Last steps:

  • make and executable in your file manager
  • change the pathes (Exec and Icon) in youplay.desktop to your pathes (e.g.: /home/yourpath/youplay)
  • copy youplay.desktop to /home/user/.local/share/applications
AUR package

The AUR package was kindly bundled by j.r. Install it with (replace yay with your AUR helper):

yay -S youplay

Operation Instructions

YouPlay supports two modes: CLI (command line mode) and GUI (graphical mode).

You can start YouPlay in CLI mode like this:

  • Navigate in a terminal to your YouPlay directory: cd /home/blabla/youplay

  • ./

  • ./ --help

  • ./ songtitle

All other options will be shown interactively.

You can also start YouPlay in GUI mode:

  • Navigate in a terminal to your YouPlay directory: cd /home/blabla/youplay
  • ./
  • or from your application menu or launcher (this requires youplay.desktop with adapted pathes, copied to /home/user/.local/share/applications/)

When the GUI shows up, you can enter a song title (min 4 characters) that you want to listen to. The App will present a list of 10 matching songs from Youtube. Select one or doubleclick to start downloading and playing it. All songs that you are listened to, are stored as mp3 files in a subfolder named 'youplay' under your standard music folder in home. A song, that was already downloaded, will not be downloaded again, as long as the file exists in the 'youplay' subfolder. You can show and play all downloaded songs with the SONG button. Just enter another search term to return to the search list.


If YouPlay does not run, please read the installation instructions again and again. If this does'nt help, contact me on my Matrix address: You're invited to talk on Matrix

Since Youtube changes the API every now and then, it is recommended to update 'youtube-dl' regularly:

pip3 install --upgrade youtube-dl

Release Notes

Version 0.31 - 2021.05.25
  • Eventually I found out how to control 'python-mpv'. This version got additional controls in GUI-Mode: Pause/Continue, Back, Forward. The Play/Stop and Pause/Continue controls are kind of overlapping in functionality, but who cares.

  • Play/Stop will either start a selected song or stop it. If you press Play again, the song will start from the beginning.

  • Pause/Continue will either pause the song at the current position, or continue playing at the position where you stopped it.

  • Back/Forward will step 5 seconds back or forward during playback.

  • I'm sure there are some glitches in edge cases, but anyway, it works.

  • Don't forget to run 'pip3 install --upgrade youtube-dl', because Google (Youtube) will continue to kick your ass.

Version 0.30 - 2021.05.18
  • Until now, all songs were download as webm-files (but named as mp3 files) because youtube-dl ignores the mp3-format parameter. Thats why YouPlay converts all downloaded songs now from webm to mp3.

  • I removed the filename sanitizer because I think it is not necessary. We will see if it causes issues with weird song names.

Version 0.29 - 2021.03.22
  • Improvement of process handling to avoid busy wait on process exit (thank you, Jürgen Hötzel :)
Version 0.28 - 2021.01.20
  • File 'audio.list' not longer required because of direct search result processing. You can delete the old audio.list (thank you, j.r :)

  • Downloaded songs will go to 'youplay' subdirectory under your standard music folder. You can delete or copy the old music subfolder (thank you Joël)

  • Search strings must be longer than 3 characters to avoid bullshit searches

  • Minor bug fixes

Version 0.27 - 2021.01.10
  • Duplicated download of existing files fixed again (song.mp3.mp3.mp3)

  • Song names are sanitized to avoid invalid search strings in youtube-dl (welle erdball c64)

Version 0.26 - 2021.01.08
  • Heavy refactoring on the CLI control loop, run ''./ --help' for more infos

  • CLI mode now shows already downloaded songs, run: './' --songs'

  • Further list alignment for song and search list, both in CLI- and GUI-mode.

  • Installation scripts and packages are 'work in progress' and not yet ready.

Version 0.25 - 2021.01.04
  • Code clean-up

  • Mutagen dependency removed (song duration is now fetched with 'ffmpeg')

Version 0.24 - 2021.01.03
  • GUI song number centered

  • Only one button to PLAY or STOP a song

  • Doubleclick on a song while another one is playing, will stop the playing song and play the doubleclicked song

  • Progress bar works when a second song is searched

  • The SONG-button will show and let you play all downloaded songs from the 'music' folder

Version 0.23 - 2020.12.23
  • GUI mode shows playing time

  • Columns and song titles are correctly adjusted to fit into window

Version 0.22 - 2020.12.21
  • GUI mode will utilize the internal python-mpv player instead of the external mpv player

  • PLAY-button will be disabled if you doubleclick song title or click the PLAY-button

Version 0.21 - 2020.12.19 (my birthday version)
  • ffmpeg dependency removed, because youtube-dl will download mp3 directly

  • Downloaded songs will be stored in the 'music' subfolder

  • Already downloaded songs will not be downloaded again, but played immediately

  • Option to save a song removed from CLI and GUI, because it is obsolete

  • PLAY button disabled when song is playing (only when started from PLAY button, not from doubleclick)

Version 0.20 - 2020.12.18
  • Info about song duration added to CLI and GUI

  • Endless streams are omitted (by duration = 0)

  • Number of songs reduced to 10 (to avoid lenghty loading time)

Version 0.19 - 2020.12.16
  • Progress bar while searching, downloading and saving songs
  • Progress bar for CLI and GUI mode
Version 0.18 - 2020.12.15
  • youplay.desktop-file doesn't require bash-script, but call directly

  • CLI-mode utilises MPV in CLI-mode

  • GUI-mode starts MPV in GUI-mode

  • Doubleclick in song list, starts download and playback of selected song

Versions before 0.18 - not documented
  • sorry


Author: Ralf Hersel

License: GPL3