Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

File organization

Organize moves and renames files into a library folder by a foobar2000-style format string, from the TUI or the desktop app. Every move is previewed before anything is touched.

In the desktop app

  1. Select tracks in the queue, or an album or artist in the library
  2. Organise… from the context menu
  3. Pick or type a pattern, and a library folder if you have more than one
  4. Read the preview
  5. Organise, then confirm the counts

Dropping a folder from Finder onto the queue indexes the files where they are and queues them, without moving anything. Organize them into the library once you have listened.

In the TUI

  1. On the queue page (1), select tracks: t tags one, Shift with the arrows or a click extends the selection, Ctrl+A takes everything
  2. Open the row's menu with m, a right click or the ⋯ at the end of the row; on an album heading it covers the whole record
  3. Choose Organize files…
  4. Pick a named pattern from your config with ↑ and ↓; the preview follows
  5. Read the preview (Tab moves to it, and ↑ ↓ scroll it)
  6. Enter moves the files; Esc closes without moving anything

A track that is playing keeps playing while it moves.

Reading the preview

Every selected file gets a row, whatever happens to it:

→ Moving. The destination is shown relative to the library folder.
✓ Already exactly where the pattern puts it. Nothing to do.
⚠ Blocked. Something already holds that path, or two files in this run resolve to it. The file stays where it is.
✗ The pattern produced nothing usable for this file.

A blocked file is listed with the destination it collided with.

Destination

Files are organized into a configured library folder (from [library] folders in your config). The TUI uses the first one; the desktop app lets you pick when there is more than one. The format pattern generates the relative path within that folder.

For example, with folders = ["/Volumes/Music/library"] and the standard pattern, a track becomes:

/Volumes/Music/library/Aphex Twin/(1999) Windowlicker EP/01. Windowlicker.flac

With no library folder configured, organize refuses to plan.

Configuring patterns

In the desktop app the pattern is a field: the preview follows what you type, and Save writes it to config.toml under a name. An unsaved pattern still previews and runs. Patterns can also be written in the config:

[organize]
default = "standard"       # preselected in the TUI modal and the macOS sheet
move_ancillary = true      # cover art, .cue and .log travel with the music

[organize.patterns]
standard = "%album artist%/(%date%) %album%/%tracknumber%. %title%"
va-aware = "%album artist%/$if($stricmp(%album artist%,Various Artists),,['('$left(%date%,4)')' ])%album% '['%codec%']'/[$num(%discnumber%,2)][%tracknumber%. ][%artist% - ]%title%"
flat = "%artist% - %title%"

va-aware puts the track artist in the file name and drops the year when the album artist is Various Artists. %date% is the date the library shows for the album: the original release date (ORIGINALDATE) where one is tagged, otherwise the release date, so a reissue is filed under the year the record came out. Files the library does not yet know are read the same way, so the preview and the move agree. Format strings has more examples and every function.

Safety