Library Management

Baander organizes your media into libraries. Each library points to a directory on disk and has a type that determines how files are indexed and what metadata is extracted. This page covers creating libraries, scanning them, watching for changes, and extracting cover art.

Creating Libraries

Use the app:library:create command to register a new media library. You must provide a name, the absolute path to the media directory, and the library type.

make exec cmd="php bin/console app:library:create 'My Music' /data/music music"

The slug is auto-generated from the name (lowercased, spaces replaced with hyphens, special characters removed). Provide --slug to override it:

make exec cmd="php bin/console app:library:create 'My Music' /data/music music --slug my-music-collection"

The library path must be accessible from inside the app container. Mount the directory as a volume in docker-compose.yml before creating the library.

See the full command reference for all options including --sort-order.

Scanning

After creating a library, run a scan to index its contents:

make exec cmd="php bin/console app:library:scan my-music"

The scan performs these steps:

1. File discovery -- recursively walks the library directory and collects all files with recognized media extensions
2. Metadata extraction -- reads tags from audio files (title, artist, album, track number, duration) and video files (title, duration, resolution)
3. External enrichment -- queries external APIs to fill in missing metadata such as genre, year, cover art URLs, and artist biographies

Scanning is idempotent. Running it multiple times on the same library will update existing records and add new files without creating duplicates. Removed files are cleaned up on subsequent scans.

See the command reference for details. Metadata enrichment depends on the External APIs configuration.

File Watching

For continuous monitoring of a library directory, use the app:watch-files command. It uses Linux inotify to detect file system events in real time:

make exec cmd="php bin/console app:watch-files --path /data/music"

Watch multiple directories at once:

make exec cmd="php bin/console app:watch-files --path /data/music --path /data/movies"

The watcher detects four event types:

Adjust the read timeout with --timeout (in milliseconds, default 5000):

make exec cmd="php bin/console app:watch-files --path /data/music --timeout 10000"

If no --path is given, the command watches the current working directory.

See the command reference for details.

Supported Media Formats

Baander detects file types by reading magic bytes from the file header, falling back to extension-based detection when headers are ambiguous.

Audio formats

Video formats

Cover Art Extraction

After scanning a music library, extract embedded cover art from audio files:

make exec cmd="php bin/console app:albums:extract-covers"

The command queries the database for albums without cover art and dispatches an asynchronous job for each one. Each job reads embedded image data (typically from ID3v2 APIC frames in MP3 files or Vorbis COMMENT blocks in FLAC/OGG files) and stores it as the album cover.

Key points:

• Processing is asynchronous via the message bus. The command returns after dispatching all jobs.
• Albums are processed in batches of 500.
• The command is safe to run repeatedly -- it only targets albums that do not already have a cover.
• If all albums already have cover art, the command exits immediately.

See the command reference for details.

Next Steps

• External APIs -- configure Discogs, Last.fm, Spotify, MusicBrainz, and TasteDive for metadata enrichment during scans
• Transcoding -- set up on-demand media conversion for streaming and quality tiers
• CLI Reference -- full list of available console commands