FFPlay Shuffle Player — Documentation

Overview

FFPlay Shuffle Player is a lightweight audio/video player using ffplay with:

• Shuffle playback
• Playlist management (SQLite database)
• MPRIS support for media keys (Play, Pause, Next, Previous)
• Interactive CLI for on-the-fly control

---

Installation / Setup

1. Ensure ffplay is installed:

ffmpeg -version

2. Ensure pydbus and PyGObject are installed:

# Fedora
sudo dnf install python3-pydbus python3-gobject

3. Make sure your music index database exists:

# Default location: ~/.local/share/music_index.db
# Use your index script to populate it
./index.py scan ~/Music

4. Make the player executable:

chmod +x shuffle_player.py

---

Running the Player

# Play all tracks from the database
./shuffle_player.py --all

# Play a specific playlist
./shuffle_player.py MyFavorites

• Tracks are shuffled by default.
• Playlist tracks are sorted by filename before shuffling.

---

Media Keys / MPRIS

• Play / Pause → triggers ffplay pause/resume
• Next → skips to next track
• Previous → goes to previous track

Works with DEs supporting MPRIS (GNOME, KDE, XFCE, etc.)

---

Interactive CLI Commands

While the player is running, you can enter commands in the terminal:

Command	Description
add <playlist_name>	Add the currently playing track to a playlist. Creates the playlist if it doesn’t exist.
remove <playlist_name>	Remove the currently playing track from a playlist.
next	Skip to the next track in the playlist.
prev	Go to the previous track.
pause	Pause the currently playing track.
play	Resume playback if paused.
quit	Stop playback and exit the player.

Example:

Command (add <playlist>, remove <playlist>, next, prev, pause, play, quit): add LoveSongs
Command (add <playlist>, remove <playlist>, next, prev, pause, play, quit): next

---

Playlist Behavior

• Playlists are stored in the SQLite database:

  • Table playlists: id, name
  • Table playlist_tracks: playlist_id, track_id

• Adding/removing tracks does not delete the files from disk.

• When playing from a playlist, next and prev navigate only within that playlist.

---

Shuffle Behavior

• Tracks are randomly shuffled on player startup.
• Auto-next is enabled: when a track finishes, the next one starts automatically.

---

FFplay Integration

• Audio from audio/video files is supported.
• ffplay runs without display: -nodisp -vn
• Logs are silenced (-loglevel quiet) for a clean terminal experience.

---

Notes

• CLI commands run in a background thread → media keys still work.
• If you want to play arbitrary folders, you can use your shell scripts to populate the database or call the player with playlist names.