Festival GUI

Festival, the standalone GUI client.

To view this documentation locally, run:

festival --docs

Key/Mouse shortcuts

[A-Za-z0-9]Jump to search tab
CTRL+SSave Changes
CTRL+ZReset Changes
CTRL+CReset Collection
CTRL+AAdd Scan Directory
CTRL+WRotate Album Sort
CTRL+ERotate Artist Sort
CTRL+RRotate Song Sort
CTRL+DGoto Last Tab
UpLast Tab
DownNext Tab
RightLast Sub-Tab
LeftNext Sub-Tab
Primary MouseSet Artist, Album, Song
Secondary MouseAdd Artist, Album, Song to Queue
Middle MouseCopy Artist, Album, Song text
CTRL+PrimaryAdd Artist, Album, Song to Playlist
CTRL+SecondaryOpen Album/Song Directory
CTRL+MiddleCopy Artist/Album/Song PATH

Note: CTRL is Control on macOS.

Command Line

Festival has some command line flags, useful for adjusting playback.

Some examples:

Play the next song:

./festival --next

Seek backwards 25 seconds in the current song:

./festival --seek-backward 25

Skip 3 songs into the queue:

./festival --skip 3

Play the 10th song in the queue:

./festival --index 10

The full list of commands:

Usage: festival [OPTIONS]

          Start playback

          Pause playback

          Toggle playback (play/pause)

          Skip to next track

          Play previous track

          Clear queue and stop playback

          Clear queue but don't stop playback

          Shuffle the current queue and reset to the first song

          Turn on single `Song` track repeat

          Turn on queue repeat

          Turn off repeating

      --volume <VOLUME>
          Set the volume to `VOLUME` (0-100)

      --seek <SEEK>
          Seek to the absolute `SEEK` second in the current song

      --seek-forward <SEEK_FORWARD>
          Seek `SEEK_FORWARD` seconds forwards in the current song

      --seek-backward <SEEK_BACKWARD>
          Seek `SEEK_BACKWARD` seconds backwards in the current song

      --index <INDEX>
          Set the current song to the index `INDEX` in the queue.
          The queue index starts from 1 (first song is `--index 1`).
          Providing an index that is out-of-bounds
          will end the queue (even if repeat is turned on).

      --skip <SKIP>
          Skip `SKIP` amount of songs
          If the last song in the queue is skipped over,
          and queue repeat is turned on, this will reset
          the current song to the 1st in the queue.

      --back <BACK>
          Go backwards in the queue by `BACK` amount of songs
          If `BACK` is greater than the amount of songs we can
          skip backwards, this will reset the current song to
          the 1st in the queue.

          Open documentation locally in browser
          This opens `Festival'`s documentation in a web
          browser, and does not start `Festival` itself.

          Print the PATH used by Festival
          All data saved by Festival is saved here.
          For more information, see:

          Print JSON metadata about the current `Collection` on disk
          This output is not meant to be relied on (yet).
          It it mostly for quick displaying and debugging
          purposes and may be changed at any time.
          This flag will attempt to parse the `Collection` that
          is currently on disk and extract the metadata from it.
          This also means the entire `Collection` will be read
          and deserialized from disk, which may be very expensive
          if you have a large `Collection`.

          Disable watching the filesystem for signals
          The way a newly launched Festival communicates to
          an already existing one (e.g, `festival --play`) is
          by creating a file in Festival's `signal` directory.
          `festival --FLAG` just creates a file in that directory,
          which an existing Festival will notice and do the appropriate task.
          Using `--disable-watch` will disable that part of the system so that
          filesystem signals won't work, e.g, `festival --play` will not work.

          Disable OS media controls
          Festival plugs into the native OS's media controls so that signals
          like `play/pause/stop` and/or keyboard controls can be processed.
          `--disable-media-controls` disables this.

          Delete all Festival files that are currently on disk
          This deletes the entire `GUI` Festival folder, which contains:
          - The `Collection`
          - The `Playlists`
          - `GUI` settings (sort methods, color, etc)
          - `GUI` state (currently selected album/artist, etc)
          - Audio state (currently playing song, queue, etc)
          - Cached images for the OS media controls
          - Documentation files
          The PATH deleted will be printed on success.

          Set filter level for console logs
          [default: INFO]

  -v, --version
          Print version

  -h, --help
          Print help (see a summary with '-h')


Festival saves all of its files within the "OS data" directory.

You can delete this folder to reset Festival's state/settings and the Collection, or more easily, just run:

./festival --delete
macOS$HOME/Library/Application Support/Festival/gui/Users/Hinto/Library/Application Support/Festival/gui
Linux$XDG_DATA_HOME/festival/gui or $HOME/.local/share/festival/gui/home/hinto/.local/share/festival/gui

Festival saves everything into gui because other frontends will use the same festival project directory, e.g:

├─ gui/
├─ daemon/
├─ cli/

The sub-directories and files within gui/ and their purpose:

├─ gui/
   ├─ state/
   ├  ├─ audio.bin      # Audio state, e.g: elapsed time, current song.
   ├  ├─ collection.bin # The main music `Collection`, holds metadata and PATHs to audio files.
   ├  ├─ playlists.bin  # The `Playlists` database, holds all info about all playlists.
   ├  ├─ settings.bin   # `GUI`-specific settings, e.g: sorting methods, album size.
   ├  ├─ state.bin      # `GUI`-specific state, e.g: current tab, search input.
   ├─ docs/  # Documentation files from `festival --docs`
   ├─ image/ # These are resized images of the album art.
   ├         # Festival itself does not need these (all images are
   ├         # within `collection.bin` itself) however, Festival hooks
   ├         # into the OS's native controls which needs a PATH to an
   ├         # image to display it. These are for that.
   ├─ signal/ # This is how Festival communicates with an existing one
   ├          # (e.g `festival --play`), via filesystem-based signals.
   ├          # `festival --play` quite literally just creates an empty
   ├          # file inside this folder called `play`.
   ├─ txt/
      ├─ crash.txt  # Crash/panic data. Useful for bug reports.
      ├─ perf.json  # Collection creation performance timings, in JSON.


Festival's playlists are not necessarily tied to a Collection.

For example, after a Collection reset, the songs in a playlist may not exist anymore.

The way Festival handles this is to continue holding onto the "invalid" playlist indefinitely.

Upon every Collection reset, Festival will check every "invalid" playlist entry and attempt to "recover" it.

If a matching song with the correct metadata is found after a Collection reset, any "invalid" playlist entry that was referencing it will automatically recover.