Library

The Library panel manages your music catalog: folders, scans, shadow libraries, and the track list.

What it does

• Add Folder — Add a root folder for music, podcasts, or audiobooks. iPodRocks scans it recursively.
• Scan Library — Re-scan all folders to pick up new or changed files. Uses content hashes to skip unchanged files.
• Clear scan cache — Reset content hashes so the next scan re-processes all files (use when tags or files changed externally).
• Harmonic data banner — Shows how many tracks have key/BPM data. Links to Settings to enable extraction and Essentia analysis.
• Library Folders — Compact list of added folders with remove option.
• Shadow Libraries — Pre-transcoded mirrors (e.g. FLAC → MPC). Create, rebuild, or delete them.
• Track list — Search, sort, and filter by device, type, sync status, and playlist. Selecting a playlist from the filter dropdown narrows the list to that playlist's tracks. (The separate Playlists tab was removed in 2.0.0; full playlist management lives in the Playlists panel.)
• Broken-playlist banner — If a re-scan removes tracks that playlists still reference, a warning banner appears here with a link to repair or delete the affected playlists.
• Preview tracks — double-click a track to play it in the persistent player bar at the bottom of the window.

How it works

• Scan reads file tags (artist, album, title, genre, etc.) and optionally key/BPM via metadata or Essentia. It stores content hashes to skip unchanged files on the next scan.

• Album artwork lives beside the audio, not inside it. A shadow library gets one cover.jpg per album folder, resized to 300px — the file Rockbox reads. Artwork is deliberately not embedded into the transcoded files themselves; doing so put a full-resolution copy of the cover inside every single track.

• Shadow libraries are built once; devices can use them as the source instead of the primary library for faster sync (no on-the-fly transcoding). A shadow library is a file-only mirror — it contains the transcoded audio files and copied album artwork, nothing else. Play counts, ratings, and listening history are not stored in or synced through shadow libraries; they live in the primary library database and are updated by importing Rockbox's runtime data from the device. When the primary library changes, shadow libraries are kept in sync automatically (adds, updates, and removes propagate) — a shadow library is meant to mirror your library exactly, differing only in codec.

• Rebuild — The ⟳ button on a shadow library row. It does not re-encode what is already there: files that match the library's codec configuration are adopted as they stand, and only missing or mismatched tracks are converted. It never opens a file that already exists, so it cannot change anything about one — not its tags, not its ReplayGain. Use it when a shadow library has lost track of its files but the transcoded folder is intact.

  To actually rewrite existing files — for instance because a version before 2.3.3 wrote their Musepack ReplayGain into the tag instead of the stream header where Rockbox reads it, or embedded a full-size cover in every one — delete the shadow library with the "delete the files too" option and create it again. That re-encodes everything from the source, correctly. The new files differ in size and timestamp, so your next sync copies them to the device as well.

  Note that a shadow library mirrors your library's folder layout, not its tags. Renaming an album in a tag editor that also renames the folder on disk moves the shadow file with it (the old transcode is deleted on the next scan); editing only the album tag leaves the file where it is, and the shadow copy keeps the tag it was transcoded with — a shadow file is only rewritten when it is missing, when its folder path changes, or when it does not match the library's codec configuration. To pick up a tag-only edit, delete the shadow library keeping its files and create it again at the same folder: the mismatched tracks are re-transcoded and the rest are adopted.

• Prune orphan files — The ⚙ button on a shadow library row offers a one-shot cleanup that deletes files the main library no longer accounts for. Versions before 2.3.0 did not remove a transcode when its album was renamed or deleted, so shadow libraries built with those versions can hold several copies of the same album under different names. Album artwork is kept for albums that still exist, folders emptied by the cleanup are removed, and nothing outside the shadow library's own folder is ever touched. If the shadow folder is not reachable (an unplugged drive) the prune refuses to run rather than treating every file as an orphan. Renames and deletions from 2.3.0 onward are cleaned up automatically during the scan — the prune is only for the backlog.

• Variable bitrate (VBR) — When creating a shadow library with a lossy codec (MP3, AAC, OGG, Opus), tick Variable bitrate (VBR) to encode at a quality level derived from the chosen bitrate instead of a fixed bitrate — usually better quality per file size. The option only shows for these codecs; lossless codecs (FLAC/ALAC) are always variable and Musepack is already quality-based, so it is hidden for them.

• The track list is virtualized for large libraries. Filters (device, type, on device, playlist) apply in memory.

How to work with it

1. Before scanning: Enable "Extract harmonic data" and "Analyze with Essentia" in Settings if you want key/BPM for Savant and harmonic mixing. Then add folders and scan.
2. After adding a folder: A scan runs automatically. Wait for it to finish before syncing.
3. Shadow libraries: Create one if you sync to a device that needs a different codec (e.g. MPC). Point the device to the shadow in Devices.
4. Shadow library larger than it should be? If it holds albums you renamed or deleted long ago, open its ⚙ menu and run Prune orphan files. Run it once; after that the app keeps itself tidy.
5. Clear cache: Only when you know files or tags changed outside iPodRocks and you want a full re-scan.

Music Preview Player

Double-click any track in the library list to start playback in the player bar that appears at the bottom of the window.

Queue — The panel's currently filtered track list becomes the playback queue. Next/Previous navigate within it; playback stops automatically after the last track.

Controls — Play/pause, previous (restarts the current track if more than 3 seconds in, otherwise jumps to the previous track), stop, next, seek slider (0.5 s granularity), volume slider, mute toggle, and close (✕) to dismiss the player.

Persistence — Volume and mute state are remembered across sessions via localStorage.

Format support — Native playback for MP3, AAC, FLAC, OGG, Opus, PCM, and ALAC. Musepack, APE, WAV, and AIFF are transcoded to Ogg Vorbis on demand via FFmpeg the first time you press play; the transcoded copy is stored in a temp directory and reused on subsequent plays.

Caveats — Missing or unreadable files fail silently in the player bar. Transcoding errors are logged to the console. There is no pre-cache; each transcode happens on demand at playback time.

Rocksy

Rocksy can browse and manage your library from the chat:

• "What artists do I have in Rock?" → library_list_artists (also library_list_albums, library_list_genres)
• "Search my library for Bowie" → library_search_tracks
• "Add /Users/me/Music as a library folder" → library_add_folder (asks you to confirm first)
• "Remove that folder" → library_remove_folder (asks you to confirm first)
• "Rescan my library" → library_scan (asks you to confirm first)

Read tools run immediately; anything that adds/removes folders or scans pauses for a Confirm / Cancel prompt.