Skip to main content

Watch music videos in real-time for the songs playing on your device

Project description



Watch music videos in real-time for the songs playing on your device

Build Status PyPi version AUR version


Table of contents


By default, Vidify includes the Spotify APIs and python-vlc for the player (you'll need VLC installed, too).

  • With pip: pip install --user vidify. Optional APIs or Players can be installed with pip install --user vidify[extra1,extra2]. See the APIs section and the Players section for all the extra dependencies available.
  • Otherwise, the latest stable releases have pre-compiled binaries for Windows and Linux.
  • Other installation methods for Linux:
    • Any distro: you can use snap to install it: snap install vidify-qt.
    • Arch Linux: you can install it from the AUR: vidify. Maintained by me (marioortizmanero).
    • Gentoo: there's an e-build maintained by AndrewAmmerlaan at media-video/vidify.
    • Feel free to upload it to your distro's repositories! Let me know in an issue so that I can add it to this list.

Note: Vidify requires Python >= 3.6.

The APIs

An API is simply a source of information about the music playing on a device. For example, the Spotify desktop client, or iTunes. This app is built to support any API as easily as possible, because there are many different ways to play music. Here are the currently supported ones:

Name Wiki link Extra requirements Description
Linux Media Players (mpris_linux) 🔗 Installed by default (see wiki) Any MPRIS compatible media player for Linux or BSD (99% of them, like Spotify, Clementine, VLC...).
Spotify for Windows & MacOS (swspotify) 🔗 Installed by default The Spotify desktop app for Windows & MacOS, using the SwSpotify library.
Spotify Web (spotify_web) 🔗 Installed by default The official Spotify Web API, using Tekore. Check the wiki for more details on how to use it.
Unknown (any other string) - - If you use any other string with --api, the initial screen to choose an API will appear again. This is temporary until the GUI menu is implemented.

The internal name inside parenthesis is used for the arguments and the config options. --api mpris_linux would force using the Linux Media Players API, for instance.

The players

The embedded video players inside the app. Vidify uses external players because they already come with codecs installed. The default one is VLC because it's more popular, but you can use others if you have the player installed, and the Python extra dependencies. For example, to install Vidify with Mpv support, you'd run pip install --user vidify[mpv], which installs python-mpv.

Name Extra requirements Description Arguments/config options
VLC (vlc) Installed by default The default video player. Widely used and very solid. --vlc-args <VLC_ARGS>
Mpv (mpv) python-mpv A simple and portable video player. --mpv-flags <MPV_ARGS> (only boolean flags)

For now, the only way to specify what player to use is with arguments or inside the config file with the internal name. You can use --player mpv or save it in your config file for future usage:

player = mpv

Audio synchronization

Vidify has an audio synchronization feature currently under testing. The full repository is in vidify/audiosync, being a separate repo so that it can be installed optionally.

This feature is only available on Linux for now. It's much more precise on a lightweight video player like Mpv. You can install it with pip install vidify[audiosync], along with the following dependencies:

  • FFTW: libfftw3 on Debian-based distros.
  • ffmpeg: ffmpeg on most repositories. It must be available on your path.
  • pulseaudio: pulseaudio, pre-installed on most repos.
  • youtube-dl: this is installed by default with Vidify, but make sure it's available on your path.

It's also available as vidify-audiosync on the AUR, and it comes pre-installed in the vidify snap.

Finally, you can activate the feature with --audiosync or inside your config file:

audiosync = true

You can calibrate the audiosync results with the option --audiosync-calibration or audiosync_calibration. By default it's -800 milliseconds, but it may depend on your hardware.

Note: if when using audiosync there's no sound, you might need to disable stream target device restore by editing the corresponing line in /etc/pulse/ to load-module module-stream-restore restore_device=false.

Note 2: you should make sure that the sink being recorded is either audiosync, or the one where the music is playing. Here's an example on Pavucontrol (it's usually called 'Monitor of ...'):



The app has an interface that will guide you through most of the set-up, but you can use command line arguments and the config file for more advanced options (and until the GUI is completely finished).

usage: vidify [-h] [-v] [--debug] [--config-file CONFIG_FILE] [-n] [-f] [--dark-mode] [--stay-on-top]
              [--width WIDTH] [--height HEIGHT] [-a API] [-p PLAYER] [--audiosync]
              [--audiosync-calibration AUDIOSYNC_CALIBRATION] [--vlc-args VLC_ARGS]
              [--mpv-flags MPV_FLAGS] [--client-id CLIENT_ID] [--client-secret CLIENT_SECRET]
              [--redirect-uri REDIRECT_URI]
Argument Description
-n, --no-lyrics do not print lyrics.
-f, --fullscreen play videos in fullscreen mode.
--dark-mode enables dark mode for the GUI.
--stay-on-top the app window will stay on top of other apps.
--width <WIDTH> set the width for the downloaded videos (this is useful to play lower quality videos if your connection isn't good).
--height <HEIGHT> set the height for the downloaded videos.
-a, --api specify the API to use. See the APIs section for more info about the supported APIs.
-p, --player specify the player to use. See the Players section for more info about the supported players.
--audiosync enables the Audio Synchronization feature (disabled by default).
--audiosync-calibration You can calibrate the delay in milliseconds audiosync returns with this. It can be positive or negative. The default is 0ms.
--config-file <PATH> indicate the path of your config file.

The config file

The configuration file is created by default at your usual config directory:

  • Linux: ~/.config/vidify/config.ini (or in $XDG_CONFIG_HOME, if defined)
  • Mac OS X: ~/Library/Preferences/vidify/config.ini
  • Windows: C:\Users\<username>\AppData\Local\vidify\vidify\config.ini

You can use a custom one by passing --config-file <PATH> as an argument. The config file is overriden by the configuration passed as arguments, but keeps your settings for future usage. Here's an example of one. It uses the INI config file formatting. Most options are inside the [Defaults] section.

All the available options for the config file are the same as the arguments listed in the Usage section, except for --config-file <PATH>, which is only an argument. Their names are the same but with underscores instead of dashes. For example, --use-mpv would be equivalent to use_mpv = true.


Vidify doesn't work correctly with Python 3.8 and PySide2

PySide2 started supporting Python 3.8 with the 5.14 release. Make sure you're using an updated version and try again. TypeError: 'Shiboken.ObjectType' object is not iterable will be raised otherwise.

ModuleNotFoundError: No module named 'gi' when using a virtual environment

For some reason, python-gobject may not be available inside a virtual environment. You can create a symlink inside it with:

ln -s "/usr/lib/python3.8/site-packages/gi" "$venv_dir/lib/python3.8/site-packages"

or install it with pip following this guide.

Vidify doesn't recognize some downloaded songs

If the song doesn't have a metadata field with the title and the artist (the latter is optional), Vidify is unable to know what song is playing. Try to modify the metadata of your downloaded songs with VLC or any other tool.


Helpful documentation links for contributing:

The app logo was created by xypnox in this issue.

The changelog and more information about this program's versions can be found in the Releases page.


You can run the module locally with python -m vidify.

This project uses unittest for testing. Run them with python -m unittest.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for vidify, version 2.1.0
Filename, size File type Python version Upload date Hashes
Filename, size vidify-2.1.0.tar.gz (2.1 MB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page