rekordbox-edit 0.11.0.dev3__tar.gz → 0.11.0.dev4__tar.gz

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/.github/workflows/cd.yml

@@ -105,7 +105,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Create GitHub Pre-Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
         with:
           token: ${{ secrets.WORKFLOW_TOKEN }}
           tag_name: canary-v${{ steps.version.outputs.version }}

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/.github/workflows/release.yml

@@ -49,7 +49,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Release
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
         with:
           token: ${{ secrets.WORKFLOW_TOKEN }}
           body_path: release-notes.md

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/.gitignore

@@ -55,5 +55,6 @@ site/
 
 # Superpowers SDD scratch
 .superpowers/
+docs/superpowers/
 
 worktrees/

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/CHANGELOG.md

@@ -1,6 +1,204 @@
-## v0.11.0.dev3 (2026-08-31)
-
-
+## v0.11.0.dev4 (2026-09-05)
+
+
+- chore(deps): update dependency pydantic to v2.13.5 (#208)
+- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+- chore(deps): update dependency ty to v0.0.77 (#209)
+- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+- chore(deps): update dependency platformdirs to v4.11.7 (#207)
+- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+- chore(deps): update softprops/action-gh-release digest to efb3536 (#206)
+- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
+
+## v0.11.0 (2026-09-02)
+
+
+- feat(convert)!: require --format-out
+- BREAKING CHANGE: --format-out and ConvertRequest.format_out no longer
+default to aiff. A run that picked its own target format was a guess at
+what the caller wanted.
+- docs: state what --yes means in one place
+- The rule is that --yes takes the default answer to every prompt, and that a
+gate's default is no. Each command page now links to it rather than
+restating it.
+- feat(convert): ask before overwriting existing output files
+- Existing output files were skipped with only a warning count, so a run could
+pass over them without the user noticing. The prompt defaults to no, and
+--overwrite answers it up front.
+- feat(convert)!: default --delete-originals to none
+- BREAKING CHANGE: the default changes from lossless to none. Deleting a
+source file now takes an explicit --delete-originals on the command line,
+so `rbe convert --yes` no longer removes originals nobody asked it to.
+- feat(edit)!: replace --force with --allow-missing and --allow-mismatch
+- BREAKING CHANGE: --force and EditRequest.force are replaced by one flag per
+gate, --allow-missing and --allow-mismatch, so authorizing a path with no
+file behind it no longer also authorizes cues landing misaligned.
+FieldHandler.forceable_skip_reasons becomes gated_skip_reasons, mapping each
+reason to the request field that lifts it.
+- refactor(edit)!: drop --multi
+- BREAKING CHANGE: --multi is removed, along with EditRequest.multi and the
+API guard behind it. --yes alone authorizes an edit across every matched
+track, and an API caller has dry_run to inspect a plan first.
+- docs: rewordings
+- docs: reword the write guards and skip reasons
+- One skip message was keyed on "length_mismatch (override with --force)",
+which no SkippedTrack.reason can equal, so that reason went unreported. The
+suffix belongs in the message. A test now asserts every key is a SkipReason.
+- refactor(cli): move _click into the cli package
+- Only cli modules imported it, but it sat at the package root. PrintChoice
+went to logger.py, whose set_level is its real consumer and which is not a
+click construct, so no root module now imports click or the cli package.
+- fix(edit): report the tracks it passed over
+- edit named skipped tracks in no code path: the held-back message sat after
+the --yes branch had already returned, and _print_edit_result counted only
+what it applied. A filter matching 30 tracks and editing 4 looked like it
+found 4. convert and import already did this.
+- feat(import): add --interactive, and let --dry-run walk directories
+- import was the only write command without per-item confirmation. Its walk
+gate also treated --dry-run as unauthorized, so previewing a directory was
+refused even though it writes nothing and previewing is how you inspect what
+a walk covers.
+- A newly created track placed in a playlist stays one op, so it asks once.
+- docs: match the guard and multi-flag changes
+- The refusal now fires where the write happens rather than before the
+preview, and --multi is only required of an unattended run, so the examples
+that paired it with --dry-run or an interactive run no longer need it.
+- fix(cli): reject --interactive alongside --yes or --dry-run
+- Both commands branched on `yes or dry_run` and returned before reading
+interactive, so the flag was discarded without a word. The scripting-mode
+error compounded it by advising --yes, which is what threw it away.
+- fix(edit): scope the multi guard to the unattended path
+- A dry run writes nothing, so refusing to preview a bulk edit contradicted
+the guard's own advice to inspect with one first, and it blocked
+--interactive: that path previews before prompting, so it could never reach
+the per-track confirmation it exists for. --yes and a one-shot edit() still
+need multi.
+- feat(api): guard writes in the API rather than the CLI
+- The refusal to write while Rekordbox is open, and the single-writer lock,
+were both CLI-only: any Python caller wrote underneath a running Rekordbox
+and could interleave with another process. Each write function now enters
+through writing(), and the advisory lock is re-entrant so the CLI's
+whole-run lock still nests around it.
+- A preview reaches neither check, so an interactive run refuses at the apply
+pass instead of before the preview.
+- fix(convert): report a missing FFmpeg as a missing dependency
+- convert() raised a bare RuntimeError, so main() logged it as an unhandled
+exception and asked the user to file a bug for an empty PATH. The edit path
+failed differently: FolderPathField swallowed the probe error and reported
+every track as unknown_file_type. Both now reach require_ffmpeg, the single
+presence check.
+- refactor(errors): give the API one exception hierarchy
+- Bad input, a missing dependency, and an aborted write each had their own
+unrelated base, so a caller could not catch one type and every command
+repeated its own translation. with_database now owns the mapping to exit
+codes, and confirm/UserQuit move to the CLI, leaving the shared layer free
+of click.
+- docs: note that the write pass applies only the previewed ops
+- test(query): cover find_content_by_ids
+- feat(import): import the ops the user approved
+- The write pass re-walked every requested directory, so a file created
+during the confirmation prompt was imported having never been previewed.
+It now takes the previewed ops, which also retires the second directory
+gate. _narrow_to_track_ids goes with it, unused now that interactive
+selection filters the op list directly.
+- feat(convert): convert the ops the user approved
+- The apply pass re-ran the filter and classifier, so a track that started
+matching during the confirmation prompt joined the batch unpreviewed. It
+now takes the previewed ops and re-checks each op's source and output
+paths, reporting a change as filesystem_changed.
+- feat(edit): apply the ops the user approved
+- The apply pass took the filter args and re-ran the query and classifier,
+so a row that started matching during the confirmation prompt joined the
+edit unpreviewed. It now takes the previewed ops, loads those rows by ID,
+and reports an op whose file changed as filesystem_changed.
+- fix(edit): guard the apply pass against usage errors and stale probes
+- The --multi guard can fire on the apply pass, where it reached the
+unhandled-exception handler. FolderPathField's probe cache is a
+module-scope singleton's state and outlived its request.
+- refactor(api): name the reserved USN block's upper bound
+- docs: update docs on USN reservation
+- fix(cli): refuse to write while Rekordbox is running
+- Rekordbox holds rows in memory and can write its own copy back over
+ours, so the "Continue anyway?" prompt offered a choice nobody can make
+safely. Dry runs still run: they write nothing.
+- fix: stamp all edited/converted/imported rows with a USN
+- - convert: per-file commits mean per-file stamps, so an interrupted batch leaves
+  every committed row correctly stamped.
+- - import: Artist, album, genre, and label rows created along the way take one
+  each. They are collected as they are made: add_content flushes, which
+  moves them out of session.new first.
+- fix(api): add USN stamping, wired to nothing yet
+- Reserves a block of counter values in one expression UPDATE rather than
+reading the counter and writing it back. Rekordbox writes to the same
+counter, so the naive shape loses increments silently.
+- chore(cli): Add thematic colors to console output
+- feat(convert): show a live progress display while encoding
+- A line per file in flight, capped by --threads, above an overall bar.
+Files spin rather than fill: ffmpeg reports twice a second and a track
+encodes in about two, so a per-file percentage would show three frames.
+Suppressed in scripting modes and when stdout is not a terminal.
+- refactor(logger): route console output through rich
+- Log lines and rich tables now share one renderer. Markup is disabled
+because rich reads a bracketed run as a style tag: a track named
+"Set [b].wav" would otherwise log as "Set .wav".
+- fix(convert): print the batch summary once
+- Both the API and the CLI logged "Converted N files to X", so an
+interactive run showed it twice. The API keeps its debug line; the
+user-facing summary belongs to the caller.
+- fix(convert): keep ffmpeg off the terminal with -nostdin
+- ffmpeg puts the tty in non-canonical mode to watch for keys like "q".
+Concurrent encodes race on saving and restoring that state, and the loser
+restores raw mode, leaving the shell echoing ^M instead of accepting
+Enter. One encode never showed it; four reproduce it every time.
+- docs: measure how convert scales across output formats
+- Uncompressed output is not disk-bound as assumed. ffmpeg already threads
+the decode, so the gain from --threads is the spare cores divided by
+those a single conversion already uses.
+- chore: update codecov config
+- docs(convert): document --threads and the result ordering
+- feat(convert): print progress on completion and report an interrupt
+- With several encodes in flight, a line printed at dispatch names a file
+that is not the one being worked on next. Ctrl-C now says what it kept.
+- feat(convert): add --threads to encode files concurrently
+- Defaults to min(4, cpu_count): MP3 and FLAC output scale well across
+files, while WAV and AIFF output is close to pure I/O and can get slower
+under concurrency on the external drives DJs keep libraries on.
+- refactor(convert): drain encodes through a thread pool
+- Fixed at one worker, so behavior is unchanged. Results are drained in
+submission order rather than completion order, and only as many jobs run
+ahead of the drain point as the pool is wide, so an abort cannot burn the
+whole batch's CPU first.
+- refactor(convert): snapshot each encode's inputs into a plain job
+- The encode half now takes values copied off the content row rather than
+the row itself, so it can move onto a worker thread without reaching
+back into a session that is not thread-safe.
+- docs: record how master.db behaves under concurrent access
+- Covers WAL mode, why a read opens no transaction, and how the identity
+map hides fresh data, then applies it to the plan-apply window and to
+maintaining the USN counter. Includes a glossary of the database terms.
+- refactor(cli): pass confirmation flags to the scripting guard directly
+- The guard read them off an object, so every caller built a throwaway class
+to carry two booleans it already had as locals.
+- refactor(convert): drop the record-update wrapper
+- The probe and apply halves are called directly. The wrapper only chained
+them and rebuilt a path the caller already had.
+- docs(convert): describe what an interrupted run leaves behind
+- feat(convert): report converted, failed, and unattempted counts on abort
+- A stopped batch leaves real committed work, so it exits through a plain
+error naming the failed file rather than through the crash handler.
+- feat(convert): commit each conversion in its own transaction
+- An interrupted run now leaves the database describing exactly the files
+that converted, and each original is deleted right after its own commit,
+so peak disk stays flat instead of doubling. ConvertAborted carries the
+converted, failed, and not-attempted counts to the caller.
+- feat(convert): encode to a temp file and move it into place
+- A hard kill now leaves a recognizable orphan rather than a truncated file
+at the path the database points at. Each run sweeps the destination
+directories it is about to write to.
+- refactor(convert): split the record update into probe and apply halves
+- The probe half reads the converted file without touching the session, so
+it can move onto a worker thread when encoding goes parallel. Passing the
+content row in retires a redundant re-query.
 - fix(locking): raise the scripted lock wait to 30 seconds
 - Also corrects the FAQ, which read as a blanket block on concurrent runs.
 - feat(cli): serialize write commands behind a single-writer lock

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rekordbox-edit
-Version: 0.11.0.dev3
+Version: 0.11.0.dev4
 Summary: Tools for managing and modifying a RekordBox library en-masse
 Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
 Project-URL: Repository, https://github.com/jviall/rekordbox-edit
@@ -65,14 +65,14 @@ Edit track metadata:
 
 ```bash
 # Fix a typo across every matching track title
-rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+rbe edit --title "Teh" Title --match "Teh" --replace "The"
 ```
 
 Convert audio files:
 
 ```bash
 # Preview what would be converted
-rbe convert --artist "Daft Punk" --dry-run
+rbe convert --artist "Daft Punk" --format-out aiff --dry-run
 
 # Convert all FLAC or WAV files to AIFF without confirming
 rbe convert --format flac --format wav --format-out aiff --yes
@@ -82,7 +82,7 @@ Import new tracks:
 
 ```bash
 # Import a folder into the library and an existing playlist
-rbe import "/Users/me/Music/New Tracks" --to-playlist "Recently Added" --directory --yes
+rbe import "/Users/me/Music/New Tracks" --to-playlist "Recently Added" --yes
 ```
 
 See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/README.md

@@ -43,14 +43,14 @@ Edit track metadata:
 
 ```bash
 # Fix a typo across every matching track title
-rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+rbe edit --title "Teh" Title --match "Teh" --replace "The"
 ```
 
 Convert audio files:
 
 ```bash
 # Preview what would be converted
-rbe convert --artist "Daft Punk" --dry-run
+rbe convert --artist "Daft Punk" --format-out aiff --dry-run
 
 # Convert all FLAC or WAV files to AIFF without confirming
 rbe convert --format flac --format wav --format-out aiff --yes
@@ -60,7 +60,7 @@ Import new tracks:
 
 ```bash
 # Import a folder into the library and an existing playlist
-rbe import "/Users/me/Music/New Tracks" --to-playlist "Recently Added" --directory --yes
+rbe import "/Users/me/Music/New Tracks" --to-playlist "Recently Added" --yes
 ```
 
 See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/codecov.yml

@@ -6,5 +6,11 @@ coverage:
         target: auto #default
         threshold: 1%
         base: auto
+    patch:
+      default:
+        # basic
+        target: auto
+        threshold: 1%
+        base: auto
 comment:
   require_changes: true

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/docs/api.md

@@ -17,6 +17,20 @@ Different filter kinds — `artist` and `format` above — AND together by defau
 
 `--print json` on any CLI command emits exactly these response envelopes, so the models below also document the JSON you get when scripting.
 
+## Writing Safely
+
+`edit`, `convert`, and `import_tracks` each have checks against concurrent writes. They will refuse to run while Rekordbox is open, raising
+[`RekordboxRunningError`][rekordbox_edit.errors.RekordboxRunningError], and each will grab a single-writer advisory lock for the
+duration of the write to prevent concurrent writes by other rekordbox-edit processes.
+
+## Errors
+
+Most errors these functions raise descend from
+[`RekordboxEditError`][rekordbox_edit.errors.RekordboxEditError].
+[`InputError`][rekordbox_edit.errors.InputError] also subclasses `ValueError`.
+
+::: rekordbox_edit.errors
+
 ## Functions
 
 ::: rekordbox_edit.api.search
@@ -32,83 +46,47 @@ Different filter kinds — `artist` and `format` above — AND together by defau
 The models form three layers: the [`FilterArgs`][rekordbox_edit.models.FilterArgs] base that every command shares, the per-command requests and responses, and the lower-level domain types those req/resp models are built from.
 
 ::: rekordbox_edit.models.FilterArgs
-options:
-heading_level: 3
 
 ### Search
 
 ::: rekordbox_edit.models.SearchRequest
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.SearchResponse
-options:
-heading_level: 4
 
 ### Edit
 
 ::: rekordbox_edit.models.EditRequest
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.EditResponse
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.EditResult
-options:
-heading_level: 4
 
 ### Convert
 
 ::: rekordbox_edit.models.ConvertRequest
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ConvertResponse
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ConvertResult
-options:
-heading_level: 4
 
 ### Import
 
 ::: rekordbox_edit.models.ImportRequest
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ImportResponse
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ImportResult
-options:
-heading_level: 4
 
 ### Miscellaneous
 
 ::: rekordbox_edit.models.Track
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.EditOp
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ConvertOp
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.ImportOp
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.SkippedTrack
-options:
-heading_level: 4
 
 ::: rekordbox_edit.models.SkipReason
-options:
-heading_level: 4

rekordbox_edit-0.11.0.dev4/docs/commands/convert.md

@@ -0,0 +1,81 @@
+# convert
+
+Convert audio files between formats and update the Rekordbox database to point at the new files. Cues, analysis, beatgrids, and all other metadata are preserved — see [Frequently Asked Questions](../faqs.md) for more info.
+
+## Supported Formats
+
+- **Input:** FLAC, AIFF, WAV (hi-res formats only — lossy-compressed sources are skipped)
+- **Output:** AIFF, FLAC, WAV, or MP3 (320kbps CBR), chosen with the required `--format-out`
+
+Tracks already in the target format are skipped. So are tracks whose output file already exists: `convert` counts them and asks whether to overwrite, defaulting to no. `--yes` will skip these without asking, whereas `--overwrite` will overwrite them without asking.
+
+## Bit Depth and Sample Rate
+
+All conversions target **16-bit / 44.1 kHz**, with a few nuances:
+
+- A source already at the target bit depth and sample rate converts losslessly.
+- A higher-resolution source (say 24-bit or 96 kHz) is down-sampled to the target, and is considered **lossy** even between lossless formats.
+- Other than conversion to MP3, which always encode to 44.1 kHz, a source with a lower sample rate than the target fidelity keeps its original sample rate.
+
+## Originals: Delete or Keep
+
+`--delete-originals` controls what happens to the source file after a successful conversion:
+
+- `none` (default) — never delete the original
+- `lossless` — delete the original only when the conversion lost no audio information; keep it when the conversion was lossy (MP3 output or down-sampled hi-res output)
+- `all` — always delete the original
+
+## Converting Several Files at Once
+
+`convert` operates on four files at a time by default so long as your CPU has the cores to do so. You can customize this by passing `--threads N` (or `-t N`), with your CPU's number of cores as an upper limit.
+
+Depending on your environment and target format, your mileage with more or less threads will vary. MP3 output speeds up close to linearly with more threads due to `libmp3lame` being a single-threaded process, whereas FLAC gains about a 50% with. WAV and AIFF outputs only see minor benefits, as `ffmpeg` already multithreads their decoding, and they don't require any encoding step. As such, you'll likely be limited by I/O speed rather than CPU when converting to WAV/AIFF.
+
+If you're converting across a network (like a mapped drive), more threads will likely only slow you down as each thread competes for network capacity, but if you're converting on a local drive it is likely to improve performance at least somewhat.
+
+## Interrupted Runs
+
+If a run stops partway, whether from a conversion failure, a full disk, or a Ctrl-C, everything it finished is kept and nothing is left half-converted. `convert` tells you which file it stopped on, how many converted, and how many it never got to. Rerun the same command to pick up where it left off.
+
+A track whose file has moved or been deleted since the preview is skipped, and the rest of the batch continues.
+
+## Examples
+
+```bash
+# Preview conversion
+rbe convert --format-out aiff --format flac --dry-run
+
+# Convert and skip confirmation
+rbe convert --format-out wav --artist "Burial" --yes
+
+# Convert to MP3 but delete originals
+rbe convert --format-out mp3 --playlist "Export" --yes --delete-originals all
+
+# Delete originals only where the conversion lost nothing
+rbe convert --format-out aiff --format flac --yes --delete-originals lossless
+
+# Get just the IDs of files that would be converted
+rbe convert --format-out aiff --format flac --print ids --dry-run
+
+# Convert everything a search finds
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --format-out aiff --yes
+
+# Max out your CPU to handle a batch of MP3s
+rbe convert --format-out mp3 --playlist "NeedsConverting" --threads 8 --yes
+```
+
+### Checks
+
+- Without flags, `convert` shows every planned change and asks once before applying. See [Confirmations](../filtering.md#confirmations) for how `--dry-run`, `--interactive`, and `--yes` change that.
+- `convert` will encode exactly the tracks the preview showed. If in between the time you're prompted and later confirm a new track that matches your filters lands in your library, it won't be included.
+- **Rekordbox running:** Writing while Rekordbox is open risks losing your changes, so `convert` will refuse to perform any writes. `--dry-run` is unaffected.
+- Before a large run, walk through the checklist in [What Should I Do Before Converting?](../faqs.md#what-should-i-do-before-converting)
+
+## Reference
+
+<!-- prettier-ignore -->
+::: mkdocs-click
+    :module: rekordbox_edit.cli.convert
+    :command: convert_command
+    :prog_name: rbe convert
+    :depth: 1

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/docs/commands/edit.md

@@ -15,50 +15,50 @@ rbe edit [OPTIONS] [TRACK-IDS]... FIELD
 rbe edit --exact-title "Untitled 3" Title --replace "Acid Rain"
 
 # Fix a typo across many titles (substring replacement)
-rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+rbe edit --title "Teh" Title --match "Teh" --replace "The"
 ```
 
 ## FolderPath
 
-`FolderPath` repoints a track at an audio file on disk. Because the database row carries more than the path, the edit keeps the dependent columns consistent:
+`FolderPath` repoints a track at an audio file on disk. Because several other columns are implicitly based on this path and other file metadata, the edit keeps these dependent columns consistent:
 
 - `FileNameL` always matches the new path's file name, and `OrgFolderPath` is updated when it matched the old path.
 - When the new file's size differs from the recorded `FileSize`, the file is probed and all of `FileType`, `SampleRate`, `BitDepth`, `BitRate`, `FileSize`, and `Length` are rewritten to match it.
-- When the file name changes, the `PPTH` path tag inside the track's analysis (ANLZ) files is rewritten to match. All other analysis data is preserved.
+- When the file name changes, the `PPTH` path tag inside the track's analysis (ANLZ) files is rewritten to match. All other analysis data is left alone.
 
 By default edits will be skipped in the following cases:
 
 - The new path's file does not exist.
 - The new path points to a file whose duration doesn't match what's in rekordbox _and_ the track has cues or an analysis, since those are time-indexed and would land misaligned.
-- The file's format is one Rekordbox doesn't support--always skipped.
+- The file's format is one Rekordbox doesn't support--this is always skipped.
 
-`edit` lists the held-back tracks and asks once whether to include them. Providing the `--yes` flag will skip them without prompting whereas `--force` edit them anyway. Including a missing file writes only the path columns.
+Each of the first two cases is a gate with its own flag, and `edit` lists the tracks it holds back and asks about it separately: `--allow-missing` writes a path with no file behind it, updating only the path columns, and `--allow-mismatch` accepts a duration that contradicts the stored length. Passing a flag answers its question up front, so no prompt appears. `--yes` takes the default answer to every prompt, and a gate's default is no, so `--yes` on its own leaves the held-back tracks skipped and reports them.
 
 ```bash
 # Relocate a library folder in bulk
-rbe edit FolderPath --match "/Volumes/OldDrive/Music" --replace "/Volumes/NewDrive/Music" --multi
+rbe edit FolderPath --match "/Volumes/OldDrive/Music" --replace "/Volumes/NewDrive/Music"
 
 # Point one track at a replacement file
 rbe edit --exact-title "Acid Rain" FolderPath --replace "/Users/me/Music/acid-rain-remaster.flac"
 ```
 
-## Guardrails
+## Checks
 
-- **Preview and confirm by default.** Without flags, `edit` shows every planned change and asks once before applying. `--interactive` confirms each track individually; `--dry-run` previews without writing; `--yes` confirms the default choice for all prompts without asking.
-- **Single-track by default.** When filters match more than one track, `edit` refuses unless you pass `--multi`. This prevents an unintentionally broad filter from making unintended edits across your library.
-- **Rekordbox running:** editing while Rekordbox is open risks corrupting your database. By default `edit` warns; in a non-interactive mode (e.g. `--print ids`) it throws an error.
+- Without flags, `edit` shows every planned change and asks once before applying. See [Confirmations](../filtering.md#confirmations) for how `--dry-run`, `--interactive`, and `--yes` change that.
+- `edit` writes exactly the tracks the preview showed. If in between the time you're prompted and later confirm a new track lands in your library that matches your filters, it won't be included. A track whose file changed in that window is skipped rather than written with stale metadata.
+- **Rekordbox running:** writing while Rekordbox is open risks losing your changes, so `edit` will refuse to perform any writes. `--dry-run` is unaffected.
 
 ## Examples
 
 ```bash
 # Preview a cleanup without touching the database
-rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --dry-run
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --dry-run
 
 # Apply it, confirming each track
-rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --interactive
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --interactive
 
 # Pipe a search result in and edit those exact tracks
-rbe search --playlist "Mislabeled" --print ids | rbe edit Title --match "  " --replace " " --multi --yes
+rbe search --playlist "Mislabeled" --print ids | rbe edit Title --match "  " --replace " " --yes
 ```
 
 See [Filtering](../filtering.md) for the full filter language.

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/docs/commands/import.md

@@ -31,18 +31,15 @@ It does not analyze audio. `SampleRate`, `BitDepth`, and `BPM` read as `0` on a
 
 A file that already has a row in the library but is missing from the named playlist is added to that playlist rather than skipped outright.
 
-## Directories
-
-A directory argument is walked recursively for audio files. Ran interactively, `import` reports how many files it found and asks you to confirm before continuing. `--yes` skips this prompt, and is required when providing a non-interactive `--print` mode and a directory argument.
-
 ## Skipped Files
 
-A file already in the library, matched by its resolved, case-insensitive path, is skipped rather than duplicated. One that cannot be read as audio, or that is not an audio file at all, is skipped with a warning, and the rest of the batch continues.
+A file already in the library, matched by its resolved, case-insensitive path, is skipped rather than duplicated. One that cannot be read as audio, or that is not an audio file at all, is skipped with a warning, and the rest of the batch continues. A file that disappears between the preview and the write is skipped too.
 
-## Guardrails
+## Checks
 
-- **Preview and confirm by default.** Without flags, `import` shows every track it plans to add and asks once before writing; `--dry-run` previews without writing; `--yes` confirms the default choice for all prompts without asking.
-- **Rekordbox running:** importing while Rekordbox is open risks corrupting your database. By default `import` warns; in a non-interactive mode (e.g. `--print ids`) it throws an error.
+- Without flags, `import` shows every track it plans to add and asks once before writing. See [Confirmations](../filtering.md#confirmations) for how `--dry-run`, `--interactive`, and `--yes` change that.
+- A directory argument is walked recursively for audio files. Ran interactively, `import` reports how many files it found and asks before continuing. `--yes` authorizes the walk outright, and is required alongside a non-interactive `--print` mode. `--dry-run` walks without asking, since it writes nothing.
+- **Rekordbox running:** writing while Rekordbox is open risks losing your changes, so `import` will refuse to perform any writes. `--dry-run` is unaffected.
 
 ## Reference
 

{rekordbox_edit-0.11.0.dev3 → rekordbox_edit-0.11.0.dev4}/docs/commands/search.md

@@ -15,7 +15,7 @@ rbe search --playlist "Techno" --print ids
 rbe search --playlist "Techno" --format flac --match-any
 
 # Feed results to another command
-rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --format-out aiff --yes
 ```
 
 See [Filtering](../filtering.md) for the full filter language and piping recipes.