rekordbox-edit 0.6.0.dev48__tar.gz → 0.7.0.dev6__tar.gz

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/CHANGELOG.md

@@ -1,4 +1,35 @@
-## v0.6.0.dev48 (2026-06-12)
+## v0.7.0.dev6 (2026-06-12)
+
+
+- chore: ruff formatting
+- fix(convert): encode MP3 at the target bit depth and sample rate
+- Pass ar=44100 and sample_fmt=s16p to libmp3lame instead of inheriting
+the source rate, so MP3 output always matches the 16-bit/44.1 kHz
+conversion target. MP3 ConvertOps report the target instead of None.
+- fix(convert): update MP3 bit depth and sample rate in database
+- Converting to MP3 left the source values (e.g. 24-bit/96 kHz) on the
+record. Rekordbox stores MP3s as 16-bit with the real sample rate, per
+the e2e database fixtures, so write those after conversion.
+- feat(convert): report audio properties on ConvertOp
+- Add source/output file type, bit depth, and sample rate fields so
+dry-run previews and JSON output describe each conversion fully.
+Source fields mirror the database record, the output sample rate
+clamps to the source, and MP3 output leaves bit depth and sample rate
+to the encoder.
+- fix(convert): respect bit depth and sample rate between hi-res formats
+- Hi-res conversions now explicitly target 16-bit/44.1 kHz. The target
+sample rate clamps to the source so nothing is ever up-sampled,
+down-sampled conversions count as lossy so --delete-originals lossless
+keeps those originals, and the database record is updated with the
+converted file's bit depth and sample rate.
+- Fixes #92
+- BREAKING(convert): replace --delete/--keep with --delete-originals enum
+- The tri-state boolean becomes an explicit mode: 'none' never deletes,
+'all' always deletes, 'lossless' (default) deletes only for hi-res
+output formats. Also drops the unsupported 'alac' --format-out choice,
+which crashed at conversion time.
+
+## v0.6.0 (2026-06-12)
 
 
 - chore(deps): update dependency mkdocstrings to v1

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rekordbox-edit
-Version: 0.6.0.dev48
+Version: 0.7.0.dev6
 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

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/docs/commands/convert.md

@@ -4,14 +4,26 @@ Convert audio files between formats and update the Rekordbox database to point a
 
 ## Supported Formats
 
-- **Input:** FLAC, AIFF, WAV (lossless only — lossy sources are skipped)
-- **Output:** AIFF (default), FLAC, WAV, ALAC, or MP3 (320kbps CBR)
+- **Input:** FLAC, AIFF, WAV (hi-res formats only — lossy-compressed sources are skipped)
+- **Output:** AIFF (default), FLAC, WAV, or MP3 (320kbps CBR)
 
 Tracks already in the target format are skipped, as are tracks whose output file already exists (override with `--overwrite`).
 
+## 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
 
-After a successful conversion the original file is **deleted** for lossless output (you can always convert back) and **kept** for MP3 output (the quality loss is one-way). Override either default with `--delete` or `--keep`.
+`--delete-originals` controls what happens to the source file after a successful conversion:
+
+- `lossless` (default) — 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
+- `none` — never delete the original
 
 ## Examples
 
@@ -23,10 +35,10 @@ rbe convert --format-out aiff --format flac --dry-run
 rbe convert --format-out wav --artist "Burial" --yes
 
 # Convert to MP3 but delete originals
-rbe convert --format-out mp3 --playlist "Export" --yes --delete
+rbe convert --format-out mp3 --playlist "Export" --yes --delete-originals all
 
 # Keep originals when converting to AIFF
-rbe convert --format-out aiff --format flac --yes --keep
+rbe convert --format-out aiff --format flac --yes --delete-originals none
 
 # Get just the IDs of files that would be converted
 rbe convert --format-out aiff --format flac --print ids --dry-run
@@ -37,7 +49,7 @@ rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
 
 ### Guardrails
 - Without flags, `convert` 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.
-- Editing while Rekordbox is open risks corrupting your database. By default `convert` warns; in a non-interactive mode (e.g. `--print ids`) it throws an error.
+- Editing while Rekordbox is open risks corrupting your database. By default `convert` warns and asks for confirmation (defaulting to no, so a `--yes` would exit); in a non-interactive mode (e.g. `--print ids`) it throws an error.
 
 ## Reference
 

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.6.0.dev48"
+version = "0.7.0.dev6"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/rekordbox_edit/_click.py

@@ -158,9 +158,10 @@ edit_click_options = [
 
 convert_click_options = [
     click.option(
-        "--delete/--keep",
-        default=None,
-        help="Delete or keep original files after conversion (default: delete for lossless, keep for MP3)",
+        "--delete-originals",
+        type=click.Choice(["none", "lossless", "all"], case_sensitive=False),
+        default="lossless",
+        help="When to delete original files after conversion: 'lossless' deletes them only when no audio information was lost (down-sampling and MP3 output count as lossy), 'all' always deletes them, 'none' never deletes them (default: lossless)",
     ),
     click.option(
         "--overwrite",
@@ -169,7 +170,7 @@ convert_click_options = [
     ),
     click.option(
         "--format-out",
-        type=click.Choice(["aiff", "flac", "wav", "alac", "mp3"], case_sensitive=False),
+        type=click.Choice(["aiff", "flac", "wav", "mp3"], case_sensitive=False),
         default="aiff",
         help="Output format (default: aiff)",
     ),

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/rekordbox_edit/api/convert.py

@@ -4,7 +4,7 @@ import logging
 import os
 import posixpath
 from pathlib import Path
-from typing import Tuple
+from typing import Literal, Tuple
 
 import ffmpeg
 from ffmpeg import Error as FfmpegError
@@ -26,51 +26,85 @@ from rekordbox_edit.utils import (
     get_audio_info,
     get_extension_for_format,
     get_file_type_for_format,
+    get_file_type_name,
 )
 
 logger = logging.getLogger(__name__)
 
+TARGET_BIT_DEPTH = 16
+TARGET_SAMPLE_RATE = 44100
+
+_HI_RES_CODECS = {
+    "aiff": "pcm_s16be",
+    "wav": "pcm_s16le",
+    "flac": "flac",
+}
+
 
 # ── ffmpeg helpers ────────────────────────────────────────────────────────
 
 
-def _convert_to_lossless(input_path, output_path, output_format):
-    """Convert lossless file to another lossless format, preserving bit depth."""
-    from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
+def _effective_sample_rate(source_rate: int | None) -> int:
+    """The output sample rate for a conversion: the target, clamped to the
+    source rate so a conversion never up-samples."""
+    if source_rate and source_rate < TARGET_SAMPLE_RATE:
+        return source_rate
+    return TARGET_SAMPLE_RATE
 
-    if not ffmpeg_in_path():
-        raise Exception(f"FFmpeg not found in PATH.{get_ffmpeg_directions()}")
 
-    audio_info = get_audio_info(input_path)
+def _classify_source_fidelity(
+    source_path,
+) -> Tuple[Literal["lossless", "lossy"], int]:
+    """Probe a source file and return the conversion's fidelity along with
+    its effective sample rate. "lossless" means no audio information is lost:
+    the source is at the target bit depth and at or below the target sample
+    rate. An unknown bit depth counts as lossy so originals are kept when in
+    doubt.
+    """
+    audio_info = get_audio_info(source_path)
     bit_depth = audio_info["bit_depth"]
+    sample_rate = audio_info["sample_rate"]
     logger.debug(
-        f"Source audio: bit_depth={bit_depth}, sample_rate={audio_info.get('sample_rate')}, channels={audio_info.get('channels')}"
+        f"Source audio: bit_depth={bit_depth}, sample_rate={sample_rate}, "
+        f"channels={audio_info.get('channels')}"
     )
+    effective_rate = _effective_sample_rate(sample_rate)
+    if bit_depth == TARGET_BIT_DEPTH and sample_rate == effective_rate:
+        return "lossless", effective_rate
+    return "lossy", effective_rate
 
-    codec_maps = {
-        "aiff": {16: "pcm_s16be", 24: "pcm_s24be", 32: "pcm_s32be"},
-        "wav": {16: "pcm_s16le", 24: "pcm_s24le", 32: "pcm_s32le"},
-        "flac": None,
-    }
 
-    if output_format.value not in codec_maps:
-        raise Exception(f"Unsupported lossless format: {output_format}")
+def _convert_to_hi_res(input_path, output_path, output_format, sample_rate):
+    """Convert a hi-res file to another hi-res format at the target bit
+    depth and the given sample rate, down-sampling higher-resolution
+    sources."""
+    from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
+
+    if not ffmpeg_in_path():
+        raise Exception(f"FFmpeg not found in PATH.{get_ffmpeg_directions()}")
 
-    codec_map = codec_maps[output_format.value]
-    if codec_map is None:
-        codec = output_format.value
-    elif bit_depth in codec_map:
-        codec = codec_map[bit_depth]
-    else:
-        codec = list(codec_map.values())[0]
-        logger.debug(f"bit_depth={bit_depth} not in codec map, falling back to {codec}")
+    codec = _HI_RES_CODECS.get(output_format.value)
+    if codec is None:
+        raise Exception(f"Unsupported hi-res format: {output_format}")
 
-    logger.debug(f"Selected codec: {codec} (bit_depth={bit_depth})")
+    output_kwargs = {
+        "acodec": codec,
+        "ar": sample_rate,
+        "map_metadata": 0,
+        "write_id3v2": 1,
+    }
+    # PCM codecs fix the bit depth by name; the flac encoder needs it spelled out.
+    if output_format.value == "flac":
+        output_kwargs["sample_fmt"] = "s16"
+
+    logger.debug(
+        f"Selected codec: {codec} targeting {TARGET_BIT_DEPTH}-bit/{sample_rate} Hz"
+    )
 
     try:
         (
             ffmpeg.input(input_path)
-            .output(output_path, acodec=codec, map_metadata=0, write_id3v2=1)
+            .output(output_path, **output_kwargs)
             .overwrite_output()
             .run(capture_stdout=True, capture_stderr=True)
         )
@@ -88,7 +122,8 @@ def _convert_to_lossless(input_path, output_path, output_format):
 
 
 def _convert_to_mp3(input_path, mp3_path):
-    """Convert lossless file to MP3 320kbps CBR."""
+    """Convert hi-res file to MP3 320kbps CBR at the target bit depth and
+    sample rate."""
     from rekordbox_edit.utils import ffmpeg_in_path, get_ffmpeg_directions
 
     if not ffmpeg_in_path():
@@ -101,6 +136,10 @@ def _convert_to_mp3(input_path, mp3_path):
                 mp3_path,
                 acodec="libmp3lame",
                 audio_bitrate="320k",
+                ar=TARGET_SAMPLE_RATE,
+                # libmp3lame takes planar input; s16p quantizes to 16-bit
+                # before encoding.
+                sample_fmt="s16p",
                 map_metadata=0,
                 write_id3v2=1,
             )
@@ -140,18 +179,18 @@ def _update_database_record(
     if not file_type:
         raise Exception(f"Unsupported output format: {output_format}")
 
-    if output_format.upper() in ["AIFF", "FLAC", "WAV"]:
+    converted_sample_rate = converted_audio_info["sample_rate"]
+    if converted_sample_rate:
+        content.SampleRate = converted_sample_rate
+
+    if output_format.upper() == "MP3":
+        # Rekordbox records MP3s as 16-bit (see the e2e DB fixtures); probes
+        # report no bit depth for them.
+        content.BitDepth = 16
+    else:
         converted_bit_depth = converted_audio_info["bit_depth"]
-        database_bit_depth = getattr(content, "BitDepth", None)
-        if (
-            database_bit_depth
-            and converted_bit_depth
-            and converted_bit_depth != database_bit_depth
-        ):
-            raise Exception(
-                f"Bit depth mismatch for lossless transcode: "
-                f"database={database_bit_depth}, file={converted_bit_depth}"
-            )
+        if converted_bit_depth:
+            content.BitDepth = converted_bit_depth
 
     content.FileNameL = new_filename
     content.FolderPath = converted_full_path
@@ -227,10 +266,26 @@ def _classify_convert(content, args: ConvertRequest) -> ConvertOp | SkippedTrack
             f"skip convert id={content.ID} reason=output_file_exists path={output_path}"
         )
         return SkippedTrack(id=str(content.ID), reason="output_file_exists")
+    # The DB SampleRate stands in for the probe here so dry-run previews match;
+    # the convert loop re-probes and reconciles. MP3 always encodes at the target.
+    if args.format_out.upper() == "MP3":
+        output_sample_rate = TARGET_SAMPLE_RATE
+    else:
+        output_sample_rate = _effective_sample_rate(content.SampleRate)
     return ConvertOp(
         id=str(content.ID),
         source_path=content.FolderPath or "",
         output_path=output_path,
+        source_file_type=(
+            get_file_type_name(content.FileType)
+            if content.FileType is not None
+            else None
+        ),
+        source_bit_depth=content.BitDepth,
+        source_sample_rate=content.SampleRate,
+        output_file_type=args.format_out.upper(),
+        output_bit_depth=TARGET_BIT_DEPTH,
+        output_sample_rate=output_sample_rate,
     )
 
 
@@ -300,17 +355,10 @@ def convert(
 
     assert db.session is not None
 
-    should_delete = (
-        args.delete if args.delete is not None else args.format_out.upper() != "MP3"
-    )
-    logger.debug(
-        f"convert should_delete={should_delete} "
-        f"(args.delete={args.delete}, format_out={args.format_out})"
-    )
-
     # content_map enables per-op live FolderPath / FileNameL reads in the loop.
     content_map = {str(c.ID): c for c in contents}
     converted_ops: list[ConvertOp] = []
+    lossless_op_ids: set[str] = set()
     try:
         for i, op in enumerate(ops, 1):
             content = content_map[op.id]
@@ -321,10 +369,17 @@ def convert(
                 raise RuntimeError(f"Source not found: {src}")
 
             if args.format_out.upper() == "MP3":
+                output_sample_rate = TARGET_SAMPLE_RATE
                 success = _convert_to_mp3(src, op.output_path)
             else:
-                success = _convert_to_lossless(
-                    src, op.output_path, OutputFormats(args.format_out.lower())
+                fidelity, output_sample_rate = _classify_source_fidelity(src)
+                if fidelity == "lossless":
+                    lossless_op_ids.add(op.id)
+                success = _convert_to_hi_res(
+                    src,
+                    op.output_path,
+                    OutputFormats(args.format_out.lower()),
+                    output_sample_rate,
                 )
 
             if not success:
@@ -340,7 +395,12 @@ def convert(
                 args.format_out.upper(),
             )
             converted_ops.append(
-                ConvertOp(id=op.id, source_path=src, output_path=op.output_path)
+                op.model_copy(
+                    update={
+                        "source_path": src,
+                        "output_sample_rate": output_sample_rate,
+                    }
+                )
             )
 
         db.session.commit()
@@ -355,15 +415,32 @@ def convert(
         _rollback_and_cleanup(db, converted_ops)
         raise
 
+    if args.delete_originals == "all":
+        deletable_ops = converted_ops
+    elif args.delete_originals == "lossless":
+        deletable_ops = [op for op in converted_ops if op.id in lossless_op_ids]
+    else:
+        deletable_ops = []
+    logger.debug(
+        f"convert delete_originals={args.delete_originals}: deleting "
+        f"{len(deletable_ops)}/{len(converted_ops)} source file(s)"
+    )
+
     deleted = 0
-    if should_delete:
-        for op in converted_ops:
-            try:
-                os.remove(op.source_path)
-                deleted += 1
-            except Exception as e:
-                logger.warning(f"Failed to delete {op.source_path}: {e}")
-        logger.debug(f"convert deleted {deleted}/{len(converted_ops)} source file(s)")
+    for op in deletable_ops:
+        try:
+            os.remove(op.source_path)
+            deleted += 1
+        except Exception as e:
+            logger.warning(f"Failed to delete {op.source_path}: {e}")
+
+    kept = len(converted_ops) - len(deletable_ops)
+    if (
+        args.delete_originals == "lossless"
+        and kept
+        and args.format_out.upper() != "MP3"
+    ):
+        logger.info(f"Kept {kept} original file(s) whose conversion was lossy")
 
     converted_ids = [op.id for op in converted_ops]
     try:

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/rekordbox_edit/cli/convert.py

@@ -46,11 +46,15 @@ logger = logging.getLogger(__name__)
 )
 @with_database(writes=True)
 def convert_command(db, **kwargs):
-    """Convert lossless audio files between formats and update RekordBox database.
+    """Convert hi-res audio files between formats and update RekordBox database.
 
-    Supports conversion from any lossless format (FLAC, AIFF, WAV) to:
-    AIFF, FLAC, WAV, ALAC, or MP3. Skips lossy formats and files already in
+    Supports conversion from any hi-res format (FLAC, AIFF, WAV) to:
+    AIFF, FLAC, WAV, or MP3. Skips lossy formats and files already in
     the target format.
+
+    Lossless conversions target 16-bit/44.1 kHz: higher-resolution sources
+    are down-sampled, and sources below the target keep their own sample
+    rate rather than being up-sampled.
     """
     print_opt = kwargs.pop("print_opt", None)
     dry_run = kwargs.pop("dry_run", False)

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/rekordbox_edit/models.py

@@ -74,14 +74,18 @@ class EditRequest(FilterArgs):
     multi: bool = False
 
 
+DeleteOriginalsMode: TypeAlias = Literal["none", "lossless", "all"]
+
+
 class ConvertRequest(FilterArgs):
     """Inputs for convert(): the shared track filters plus output format and original-file handling."""
 
     format_out: str = "aiff"
-    delete: bool | None = None
-    """Whether to delete the original files after conversion: True deletes them,
-    False keeps them, and None applies the per-format default (delete for
-    lossless output, keep for MP3)."""
+    delete_originals: DeleteOriginalsMode = "lossless"
+    """When to delete original files after conversion: "all" always deletes
+    them, "none" never deletes them, and "lossless" (the default) deletes them
+    only when the conversion loses no audio information. Down-sampling to the
+    conversion target counts as lossy, as does MP3 output."""
     overwrite: bool = False
 
 
@@ -143,11 +147,21 @@ class EditOp(BaseModel):
 
 
 class ConvertOp(BaseModel):
-    """A planned or performed conversion: track ID + source/output paths."""
+    """A planned or performed conversion: track ID, source/output paths, and
+    the file type, bit depth, and sample rate on each side. Source audio
+    fields mirror the database record; output fields reflect the conversion
+    target, with the sample rate clamped to the source so a conversion never
+    up-samples."""
 
     id: str
     source_path: str
     output_path: str
+    source_file_type: str | None = None
+    source_bit_depth: int | None = None
+    source_sample_rate: int | None = None
+    output_file_type: str | None = None
+    output_bit_depth: int | None = None
+    output_sample_rate: int | None = None
 
 
 # ── Response envelopes ────────────────────────────────────────────────────

{rekordbox_edit-0.6.0.dev48 → rekordbox_edit-0.7.0.dev6}/rekordbox_edit/utils.py

@@ -54,7 +54,6 @@ def get_extension_for_format(format_name: str):
         "AIFF": ".aiff",
         "FLAC": ".flac",
         "WAV": ".wav",
-        "ALAC": ".m4a",
     }
     extension = _get_extension_for_format.get(format_name.upper())
     if extension is None: