Module copy

Copying a selection out of the library, keeping the tree it sits in.

What this is for: filling a portable player, a card, an external drive — somewhere that is not a library and will never be scanned. The copy is a derived artifact, not a second catalog, and nothing here writes to the catalog or to the files it reads.

Two halves, and the split is the point. plan decides everything and touches nothing: which files, where each one lands, what had to be renamed, what could not be placed at all. Only then does the caller write. A run that can say what it is about to do before doing it is a run that can be shown to the user first — which is what --dry-run is — and, more importantly, one whose decisions can be tested without a filesystem.

The tree is kept relative to the watched root that holds the file, so a track at /Volumes/Music/Ozzy/1980 Blizzard/01.flac, scanned under /Volumes/Music, lands at <destination>/Ozzy/1980 Blizzard/01.flac. The alternative — inventing a layout from the tags — is a different feature (organising), and one this project has not decided it wants.

Modules

names

Making a path acceptable to the filesystem it is about to be written to.

transcode

Converting audio on the way out, by driving ffmpeg.

Structs

Failed

Why one file did not make it.

Item

One file to write, and where.

Plan

Everything a copy would do, decided before anything is written.

Recipe

Everything the caller chose, gathered so that a plan reads as one decision rather than as four positional booleans nobody can tell apart at the call site.

Renamed

A name the destination could not have taken as it stood.

TemporaryOutput

One exclusively created temporary directory beside a destination file.

Enums

Extras

Which files beside the audio travel with it.

ItemKind

What a file is doing in the plan, which is what lets a report say “12 albums and their covers” rather than a single undifferentiated count.

Wrote

What became of one file the plan named.

Functions

copy_one

Copies one file through isolated temporary output.

copy_one_checked

Copies a file, optionally requiring matching bytes for an existing output.

files_match

Compares file contents using fixed-size buffers, independent of file size.

inside_a_watched_root

true when a destination sits inside a folder the catalog watches.

partial_path

Recognizes the fixed temporary pathname used by older versions.

plan

Works out what copying these tracks would mean. Writes nothing, and reads the disk only to list what sits beside the audio: every other answer comes from the catalog.

staged_output_path

Project the output of one already-placed portable source, as used by serial desktop exports. This reuses codec-aware conversion and single-file placement without touching the filesystem. The caller must reject collisions between projected outputs from different staged sources.

validate_destination

Checks every existing component below a canonical destination base.

validate_filesystem_names

Checks planned names against the destination’s actual filesystem rules.

validate_new_publication

Tests hard-link publication inside an isolated directory, before transfer.

validate_source

Refuses missing or special sources without opening a potentially blocking FIFO/device. Source symlinks may resolve to an ordinary readable file.