Documentation

User guide and technical documentation for mtoc

Getting Started

Installation

Flatpak (Recommended for most users)

If you don't have Flatpak installed on your system, follow the instructions on the Flathub website.

The easiest way to install mtoc is through the Flathub store. You can also paste the following into your command line:

flatpak install flathub org._3fz.mtoc
flatpak run org._3fz.mtoc

RPM Package (Fedora 42+)

For Fedora users, mtoc is also available via COPR:

sudo dnf copr enable 3fz-asa/mtoc
sudo dnf install mtoc

Build from Source

Advanced users can build mtoc from source. See the GitHub repository for detailed build instructions.

First-Time Setup

  1. Launch mtoc - your library will start empty
  2. Click "Edit Library" or the link in the placeholder to configure your music folders
  3. Add the folder(s) containing your music collection (default: ~/Music)
    Note: directories will be scanned recursively, so there is no need to add subdirectories.
  4. Press "Scan" to index your collection
  5. mtoc will automatically extract metadata and album artwork from your files

Note: Ensure your files have at least title, artist, and album artist tags for proper organization.

System Requirements

  • OS: Linux with X11 or Wayland support
  • RAM: 4GB recommended (typical usage ~350MB)
  • Storage: SSD recommended for optimal performance
  • Graphics: OpenGL/hardware acceleration recommended
  • Dependencies: Qt6 >= 6.9, GStreamer >= 1.0, TagLib >= 2.0

User Guide

Browsing Your Library

Album Carousel

The carousel interface displays your albums in a horizontal row with smooth animations. Navigate using:

  • Mouse wheel scrolling
  • Click and drag
  • Direct touchpad manipulation with inertial flicking
  • Arrow keys for keyboard navigation

This interface is supplemental to the artist list. Selecting an album in the carousel will scroll to that album in the artist list and vice versa.

Artist List

Browse alphabetically sorted artists in the left column. Click an artist to expand and view their albums in a grid layout. Albums within an artist sorted chronologically, descending.

To expand album grids for all artists, right-click the artists tab and select "expand all".

Search

Use the search bar to quickly find artists, albums, or tracks. The search bar finds tracks, albums, and artists. The artists list will automatically scroll to and select the most relevant result as you type.

Layout Modes

mtoc offers two layout modes:

  • Wide Mode: Side-by-side "bento box" layout with album art, carousel, library browser, and queue all visible
  • Compact Mode: Dense layout with playback controls at the bottom. In compact mode, the queue, full-size album art, and lyrics are accessible via popups

Playback Controls

Starting Playback

  1. Browse to find an artist or album
  2. Click an album to view its tracks
  3. Double-click a track to play (or single-click if enabled in settings)

Gapless Playback

mtoc provides seamless album listening with gapless playback powered by GStreamer. Tracks transition smoothly with next-track preloading and a continuous audio pipeline.

ReplayGain

Automatic volume normalization is available for tracks with ReplayGain tags:

  • Album Mode: Normalizes based on album gain
  • Track Mode: Normalizes each track individually
  • Preamplification: Adjustable gain slider for fine-tuning
  • Fallback Gain: Applied to tracks without ReplayGain tags

Shuffle and Repeat

Enable shuffle mode to randomize playback order, or use repeat mode to loop your current queue or playlist.

Queue & Playlists

Queue Management

The queue shows your upcoming tracks. Right-click on tracks or albums to:

  • Add to queue (append to end)
  • Play next (insert after current track)
  • Multi-select tracks for batch operations
  • Drag and drop to reorder
  • Remove tracks from queue

Creating Playlists

  1. Build your desired queue using the queue management controls
  2. Click "Save Queue as Playlist"
  3. Enter a name for your playlist
  4. Playlist is saved as an M3U file in your configured playlist directory

Playing Playlists

Access your playlists from the Playlists view. M3U playlists created by mtoc or other music players are fully compatible.

All Songs Playlist

mtoc provides a virtual "All Songs" playlist that includes your entire library. This playlist updates automatically as your library changes and can be played sequentially or shuffled.

Lyrics

Synchronized Lyrics

mtoc supports LRC format synchronized lyrics with real-time highlighting. Click any line in the lyrics display to seek to that moment in the track.

Lyrics Sources

mtoc automatically detects lyrics from multiple sources:

  • Embedded lyrics in audio file metadata
  • External .lrc files (timestamped) in the same directory as your music
  • External .txt files (plain text) in the same directory as your music

Lyrics files are matched to tracks using fuzzy matching during library scanning.

Display Location

In Wide mode, lyrics appear integrated in the now playing pane. In Compact mode, lyrics are accessible via a dedicated popup window.

Mini Player

Accessing Mini Player

Click the "Show Mini Player" button in the main window to open the mini player. The main window can optionally be hidden when the mini player is active.

Layout Options

Choose from three mini player layouts in settings:

  • Vertical: Compact vertical layout with album art on top
  • Horizontal: Wide horizontal layout with controls side-by-side
  • Compact Bar: Minimal bar with essential controls only

Features

  • Full playback controls (play/pause, next, previous)
  • Progress bar with seeking
  • Album artwork display
  • Always-on-top option (X11/XWayland; limited on Wayland)
  • Position persistence across sessions

Configuration

Access settings from the Settings view to customize mtoc's behavior and appearance.

Playback Settings

  • Queue Action Default: Choose default behavior when adding tracks (Replace, Insert, Append, or Ask)
  • Restore Playback Position: Resume from last position on startup
  • Repeat Mode: Enable automatic repeat of queue or playlist
  • Shuffle Mode: Enable randomized playback order
  • ReplayGain Mode: Off, Album-based, or Track-based normalization
  • Preamplification: Adjust overall gain in dB
  • Fallback Gain: Gain applied to tracks without ReplayGain tags

Interface Settings

  • Theme: Dark, Light, or automatic based on system preference
  • Layout Mode: Wide, Compact, or automatic based on window size
  • Mini Player Layout: Choose between Vertical, Horizontal, or Compact Bar
  • Mini Player Behavior: Hide main window when showing mini player
  • Thumbnail Size: 100%, 150%, or 200% (affects memory usage vs. visual quality)
  • Single-click to Play: Toggle between single and double-click to play tracks
  • Minimize to Tray: Hide to system tray instead of closing

Library Settings

  • Music Folders: Add or remove directories to scan for music
  • Playlist Directories: Additional directories for M3U playlist files
  • Auto Refresh on Startup: Automatically scan for library changes on launch
  • Watch File Changes: Enable automatic library updates when files are added/removed
  • Multi-artist Support: Show collaborative albums under each contributing artist
  • Album Artist Delimiters: Configure separators for parsing multiple album artists from tags
  • Rebuild Thumbnails: Regenerate album artwork cache

Advanced Topics

Supported Audio Formats

mtoc supports the following audio formats through TagLib and GStreamer:

  • MP3: MPEG Audio Layer III
  • MP4/M4A: AAC (iTunes-encoded), ALAC (Apple Lossless)
  • FLAC: Free Lossless Audio Codec
  • OGG Vorbis: Open source lossy format
  • Opus: Modern open source codec

Ensure appropriate GStreamer plugins are installed for playback of all formats.

Keyboard Shortcuts

mtoc supports full keyboard navigation throughout the interface:

  • Arrow Keys: Navigate between interface elements and lists
  • Enter: Play selected track or album
  • Space: Play/pause playback
  • Ctrl+F: Focus search bar
  • Tab: Jump between main interface sections

Media keys are also supported through MPRIS integration for system-wide playback control.

Troubleshooting

Tracks Not Appearing

Ensure your music files have proper metadata tags:

  • Required: Title, Artist, Album Artist
  • Recommended: Album, Track Number, Year, Genre

Use a tag editor like MusicBrainz Picard to clean up metadata.

Album Art Missing

mtoc extracts album art from:

  • Embedded artwork in audio files
  • External image files (cover.jpg, folder.jpg, etc.) in the same directory as your music

If artwork is missing, ensure it's embedded in your files or present as an external image with a standard filename.

Performance Issues

For large libraries (10,000+ tracks):

  • Lower thumbnail size to 100% in settings
  • Enable file watcher instead of scanning on startup
  • Ensure you're using SSD storage
  • Close other memory-intensive applications

Flatpak Playlist Issues

If playlists aren't working in the Flatpak version, ensure playlist files are in directories accessible to the sandboxed app (typically within ~/Music or explicitly granted access via Flatseal).

Getting Help

For additional support: