feat: audio processing ve organization API uç noktaları ile unit testing eklendi

app/routes/data_processing.py

@@ -11,8 +11,9 @@ from pydantic import ValidationError
 import json
 import logging
 
-from app.schemas import AudioAugmentationOptions
-from app.services.audio_processor import process_audio
+from app.schemas import AudioAugmentationOptions, AudioConvertOptions, DatasetEntryMetadata
+from app.services.audio_processor import process_audio, convert_audio_format
+from app.services.dataset_organizer import analyze_for_organization
 
 router = APIRouter(prefix="/api/process", tags=["Data Processing"])
 logger = logging.getLogger(__name__)
@@ -44,15 +45,34 @@ async def _process_rate_limit(request: Request) -> None:
     _process_rate_store[client_ip] = hits
 
 
+async def _read_capped(file: UploadFile, max_bytes: int) -> bytes:
+    """Read an UploadFile in chunks, raising 413 if it exceeds max_bytes."""
+    chunks = []
+    total_read = 0
+    chunk_size = 1024 * 1024  # 1 MB chunks
+    while True:
+        chunk = await file.read(chunk_size)
+        if not chunk:
+            break
+        total_read += len(chunk)
+        if total_read > max_bytes:
+            raise HTTPException(status_code=413, detail={"code": "file_too_large", "message": f"File too large. Maximum size is {max_bytes // (1024*1024)} MB."})
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
 @router.post("/audio", dependencies=[Depends(_process_rate_limit)])
 async def process_audio_endpoint(
     file: UploadFile = File(...),
-    options: str = Form(default="{}")
+    options: str = Form(default="{}"),
+    mix_file: UploadFile | None = File(default=None),
 ):
     """
     Process an audio file with the given augmentation options.
     Returns the processed WAV file.
     options is a JSON string; if missing or empty, defaults to all-off.
+    mix_file: required when options.mixAudio is true — a second audio file
+    to blend into the primary track.
     """
     MAX_PAYLOAD_BYTES = 30 * 1024 * 1024  # 30 MB
     logger.info(f"Received audio processing request for file: {file.filename}")
@@ -72,13 +92,86 @@ async def process_audio_endpoint(
     if not file.content_type or not file.content_type.startswith("audio/"):
         raise HTTPException(status_code=400, detail={"code": "invalid_file_type", "message": "Invalid file type. Must be audio."})
 
+    if parsed_options.mix_audio and mix_file is None:
+        raise HTTPException(
+            status_code=400,
+            detail={"code": "missing_mix_file", "message": "mixAudio is enabled but no second file was provided."}
+        )
+    if mix_file is not None and (not mix_file.content_type or not mix_file.content_type.startswith("audio/")):
+        raise HTTPException(status_code=400, detail={"code": "invalid_file_type", "message": "Second file for mixing must be audio."})
+
     try:
         # Sanitize filename to prevent injection attacks
         safe_filename = re.sub(r'[^a-zA-Z0-9._-]', '_', file.filename or 'audio')
         if safe_filename.endswith('.wav'):
             safe_filename = safe_filename[:-4]
 
-        # Read file in chunks to enforce size limit before full allocation
+        content = await _read_capped(file, MAX_PAYLOAD_BYTES)
+        mix_content = await _read_capped(mix_file, MAX_PAYLOAD_BYTES) if mix_file is not None else None
+
+        # Process audio
+        processed_audio = process_audio(content, parsed_options, mix_with_bytes=mix_content)
+
+        # Return as downloadable file
+        output_filename = f"processed_{safe_filename}.wav"
+        return StreamingResponse(
+            processed_audio,
+            media_type="audio/wav",
+            headers={"Content-Disposition": f"attachment; filename={output_filename}"}
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail={"code": "validation_error", "message": str(e)})
+    except HTTPException:
+        # Re-raise as-is (e.g. the 413 file_too_large above) — without this,
+        # the bare `except Exception` below catches it too (HTTPException IS
+        # an Exception) and replaces a correct 413 with a misleading 500.
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error in audio processing: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during audio processing"})
+
+
+_CONVERT_MEDIA_TYPES = {
+    "wav": "audio/wav",
+    "mp3": "audio/mpeg",
+    "flac": "audio/flac",
+    "ogg": "audio/ogg",
+}
+
+
+@router.post("/audio/convert", dependencies=[Depends(_process_rate_limit)])
+async def convert_audio_endpoint(
+    file: UploadFile = File(...),
+    options: str = Form(default="{}")
+):
+    """
+    Convert an audio file to another format (wav/mp3/flac/ogg).
+    Returns the converted file for download.
+    options is a JSON string; if missing or empty, defaults to wav @ 192kbps.
+    """
+    MAX_PAYLOAD_BYTES = 30 * 1024 * 1024  # 30 MB
+    logger.info(f"Received audio conversion request for file: {file.filename}")
+
+    raw_options = options.strip() if options else "{}"
+    if not raw_options:
+        raw_options = "{}"
+    try:
+        parsed_options = AudioConvertOptions.model_validate_json(raw_options)
+    except (ValidationError, json.JSONDecodeError) as e:
+        raise HTTPException(
+            status_code=422,
+            detail={"code": "invalid_options", "message": f"Invalid options format: {e}"}
+        )
+
+    if not file.content_type or not file.content_type.startswith("audio/"):
+        raise HTTPException(status_code=400, detail={"code": "invalid_file_type", "message": "Invalid file type. Must be audio."})
+
+    try:
+        safe_filename = re.sub(r'[^a-zA-Z0-9._-]', '_', file.filename or 'audio')
+        # Strip any existing extension so we don't end up with e.g. "song.mp3.flac"
+        safe_filename = re.sub(r'\.[a-zA-Z0-9]{1,5}$', '', safe_filename)
+
         chunks = []
         total_read = 0
         chunk_size = 1024 * 1024  # 1 MB chunks
@@ -92,19 +185,61 @@ async def process_audio_endpoint(
             chunks.append(chunk)
         content = b"".join(chunks)
 
-        # Process audio
-        processed_audio = process_audio(content, parsed_options)
+        converted = convert_audio_format(content, parsed_options)
 
-        # Return as downloadable file
-        output_filename = f"processed_{safe_filename}.wav"
+        target = parsed_options.target_format
+        output_filename = f"{safe_filename}.{target}"
         return StreamingResponse(
-            processed_audio,
-            media_type="audio/wav",
+            converted,
+            media_type=_CONVERT_MEDIA_TYPES[target],
             headers={"Content-Disposition": f"attachment; filename={output_filename}"}
         )
 
     except ValueError as e:
         raise HTTPException(status_code=400, detail={"code": "validation_error", "message": str(e)})
+    except HTTPException:
+        # Re-raise as-is — see the matching comment in the /audio endpoint
+        # above for why this is needed before the bare `except Exception`.
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error in audio processing: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during audio processing"})
+        logger.error(f"Unexpected error in audio conversion: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during audio conversion"})
+
+
+@router.post("/audio/organize", response_model=DatasetEntryMetadata, dependencies=[Depends(_process_rate_limit)])
+async def organize_audio_endpoint(file: UploadFile = File(...)):
+    """
+    Analyze an audio file and return real acoustic metadata (duration,
+    tempo, key, loudness) plus auto-generated tags for dataset tagging
+    and categorization. No transformation — read-only analysis.
+    """
+    MAX_PAYLOAD_BYTES = 30 * 1024 * 1024  # 30 MB
+    logger.info(f"Received audio organization request for file: {file.filename}")
+
+    if not file.content_type or not file.content_type.startswith("audio/"):
+        raise HTTPException(status_code=400, detail={"code": "invalid_file_type", "message": "Invalid file type. Must be audio."})
+
+    try:
+        chunks = []
+        total_read = 0
+        chunk_size = 1024 * 1024
+        while True:
+            chunk = await file.read(chunk_size)
+            if not chunk:
+                break
+            total_read += len(chunk)
+            if total_read > MAX_PAYLOAD_BYTES:
+                raise HTTPException(status_code=413, detail={"code": "file_too_large", "message": f"File too large. Maximum size is {MAX_PAYLOAD_BYTES // (1024*1024)} MB."})
+            chunks.append(chunk)
+        content = b"".join(chunks)
+
+        metadata = analyze_for_organization(content)
+        return DatasetEntryMetadata(**metadata.to_dict())
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail={"code": "validation_error", "message": str(e)})
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error in audio organization: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during audio organization"})

app/schemas.py

@@ -62,5 +62,30 @@ class AudioAugmentationOptions(BaseModel):
     speed_change: bool = Field(default=False, alias="speedChange", description="Apply random speed change")
     bass_boost: bool = Field(default=False, alias="bassBoost", description="Apply bass boost equalization")
     trim_silence: bool = Field(default=False, alias="trimSilence", description="Trim leading and trailing silence")
-    mix_audio: bool = Field(default=False, alias="mixAudio", description="Mix with another audio track (placeholder)")
+    mix_audio: bool = Field(default=False, alias="mixAudio", description="Mix with a second uploaded audio track")
     add_noise: bool = Field(default=False, alias="addNoise", description="Add Gaussian noise")
+
+
+AudioTargetFormat = Literal["wav", "mp3", "flac", "ogg"]
+
+
+class AudioConvertOptions(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    target_format: AudioTargetFormat = Field(
+        default="wav", alias="targetFormat", description="Output container/codec to convert to"
+    )
+    bitrate_kbps: int = Field(
+        default=192, alias="bitrateKbps", ge=64, le=320,
+        description="Target bitrate for lossy formats (mp3/ogg); ignored for wav/flac"
+    )
+
+
+class DatasetEntryMetadata(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    duration_sec: float = Field(alias="durationSec")
+    tempo_bpm: float = Field(alias="tempoBpm")
+    key: str
+    loudness_db: float = Field(alias="loudnessDb")
+    tags: List[str]

app/services/audio_processor.py

@@ -4,26 +4,57 @@ Audio processing service for data augmentation and manipulation.
 
 import io
 import logging
+import subprocess
+import tempfile
+from pathlib import Path
+
 import numpy as np
 import librosa
 import soundfile as sf
 import scipy.signal
 from fastapi import UploadFile
 
-from app.schemas import AudioAugmentationOptions
+from app.schemas import AudioAugmentationOptions, AudioConvertOptions
 
 logger = logging.getLogger(__name__)
 
-def process_audio(file_bytes: bytes, options: AudioAugmentationOptions) -> io.BytesIO:
+# soundfile/libsndfile writes these natively — no subprocess needed.
+_NATIVE_FORMATS = {"wav": "WAV", "flac": "FLAC"}
+# Everything else (mp3, ogg) goes through ffmpeg, same subprocess pattern
+# already used elsewhere in this codebase for audio decode (see
+# feature_extractor.py / vocal_analyzer.py's _ffmpeg_decode).
+_FFMPEG_CODEC = {"mp3": "libmp3lame", "ogg": "libvorbis"}
+
+def process_audio(
+    file_bytes: bytes,
+    options: AudioAugmentationOptions,
+    mix_with_bytes: bytes | None = None,
+) -> io.BytesIO:
     """
     Process audio file with requested augmentation options.
     Returns processed audio as BytesIO (WAV format).
+
+    mix_with_bytes: a second audio file to mix in when options.mix_audio is
+    set. Silently ignored (mix skipped) if mix_audio is off or no second
+    file was provided — the route layer decides whether that's an error.
     """
     try:
         # Load audio from bytes
         # librosa.load expects a file path or file-like object
         y, sr = librosa.load(io.BytesIO(file_bytes), sr=None)
-        
+
+        # 0. Mix Audio — blend in a second track, resampled to match and
+        # looped/trimmed to the primary track's length so levels stay sane
+        # regardless of which clip is longer.
+        if options.mix_audio and mix_with_bytes:
+            y2, sr2 = librosa.load(io.BytesIO(mix_with_bytes), sr=sr)
+            if len(y2) < len(y):
+                repeats = int(np.ceil(len(y) / max(len(y2), 1)))
+                y2 = np.tile(y2, repeats)
+            y2 = y2[: len(y)]
+            y = librosa.util.normalize(y * 0.6 + y2 * 0.6)
+            logger.info("Applied mix_audio")
+
         # 1. Trim Silence
         if options.trim_silence:
             y, _ = librosa.effects.trim(y, top_db=20)
@@ -69,3 +100,47 @@ def process_audio(file_bytes: bytes, options: AudioAugmentationOptions) -> io.By
     except Exception as e:
         logger.error(f"Error processing audio: {str(e)}", exc_info=True)
         raise ValueError(f"Audio processing failed: {str(e)}")
+
+
+def convert_audio_format(file_bytes: bytes, options: AudioConvertOptions) -> io.BytesIO:
+    """
+    Convert an audio file to the requested target format.
+    Returns the converted audio as BytesIO.
+    """
+    target = options.target_format
+
+    if target in _NATIVE_FORMATS:
+        try:
+            y, sr = librosa.load(io.BytesIO(file_bytes), sr=None)
+            out_buffer = io.BytesIO()
+            sf.write(out_buffer, y, sr, format=_NATIVE_FORMATS[target])
+            out_buffer.seek(0)
+            return out_buffer
+        except Exception as e:
+            logger.error(f"Error converting audio to {target}: {str(e)}", exc_info=True)
+            raise ValueError(f"Audio conversion failed: {str(e)}")
+
+    if target in _FFMPEG_CODEC:
+        with tempfile.NamedTemporaryFile(suffix=f".{target}", delete=False) as tmp:
+            tmp_path = tmp.name
+        try:
+            result = subprocess.run(
+                [
+                    "ffmpeg", "-y", "-i", "pipe:0",
+                    "-c:a", _FFMPEG_CODEC[target],
+                    "-b:a", f"{options.bitrate_kbps}k",
+                    tmp_path,
+                ],
+                input=file_bytes,
+                capture_output=True,
+                timeout=60,
+            )
+            if result.returncode != 0:
+                logger.error(f"ffmpeg conversion to {target} failed: {result.stderr.decode(errors='replace')[:300]}")
+                raise ValueError(f"Audio conversion to {target} failed")
+            with open(tmp_path, "rb") as f:
+                return io.BytesIO(f.read())
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+    raise ValueError(f"Unsupported target format: {target}")

app/services/dataset_organizer.py

@@ -0,0 +1,161 @@
+"""
+Dataset organization service — analyzes an audio file and derives real
+acoustic metadata (duration, tempo, key, loudness, energy tier) used to
+auto-tag and categorize entries in a dataset, per the "Veri Seti
+Organizasyonu" tool advertised on the data-manipulation page.
+
+Deliberately independent from feature_extractor.py (AURIS's 49-feature
+AI-detection pipeline) — that module is tuned for AI-vs-human classification
+and pulls in a much heavier feature set than dataset tagging needs. Coupling
+this to it would make a simple tagging tool fragile to AI-detection changes.
+"""
+
+import io
+import logging
+
+import librosa
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_PITCH_CLASSES = [
+    "C", "C#", "D", "D#", "E", "F",
+    "F#", "G", "G#", "A", "A#", "B",
+]
+
+# Krumhansl-Schmuckler key profiles — standard weights for major/minor
+# key detection via correlation against the chroma vector.
+_MAJOR_PROFILE = np.array(
+    [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
+)
+_MINOR_PROFILE = np.array(
+    [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
+)
+
+
+def _detect_key(chroma_mean: np.ndarray) -> str:
+    """Correlate the mean chroma vector against all 24 rotated key profiles."""
+    best_score = -np.inf
+    best_key = "C major"
+    for shift in range(12):
+        major_rot = np.roll(_MAJOR_PROFILE, shift)
+        minor_rot = np.roll(_MINOR_PROFILE, shift)
+        major_score = float(np.corrcoef(chroma_mean, major_rot)[0, 1])
+        minor_score = float(np.corrcoef(chroma_mean, minor_rot)[0, 1])
+        if major_score > best_score:
+            best_score = major_score
+            best_key = f"{_PITCH_CLASSES[shift]} major"
+        if minor_score > best_score:
+            best_score = minor_score
+            best_key = f"{_PITCH_CLASSES[shift]} minor"
+    return best_key
+
+
+def _tempo_tag(bpm: float) -> str:
+    # librosa.beat.beat_track returns ~0 when it can't lock onto a beat at
+    # all (e.g. a sustained tone or ambient texture with no rhythm) — that's
+    # "no beat detected", not literally "slow", so tag it separately rather
+    # than lump it into the slow bucket.
+    if bpm < 1:
+        return "beatless"
+    if bpm < 76:
+        return "slow"
+    if bpm < 120:
+        return "moderate"
+    if bpm < 150:
+        return "upbeat"
+    return "fast"
+
+
+def _energy_tag(rms_mean: float) -> str:
+    # RMS on a float32 waveform normalized to [-1, 1]; these thresholds are
+    # calibrated against typical mixed/mastered music, not raw voice memos.
+    if rms_mean < 0.03:
+        return "ambient"
+    if rms_mean < 0.08:
+        return "calm"
+    if rms_mean < 0.15:
+        return "energetic"
+    return "intense"
+
+
+def _loudness_lufs_approx(y: np.ndarray) -> float:
+    """
+    Rough integrated-loudness estimate in LUFS-like dB, using RMS as a
+    stand-in for full ITU-R BS.1770 K-weighting (that needs a dedicated
+    filter chain this tool doesn't need for a dataset-tagging heuristic).
+    """
+    rms = float(np.sqrt(np.mean(np.square(y)))) if len(y) else 0.0
+    if rms <= 0:
+        return -70.0
+    return round(float(20 * np.log10(rms)), 1)
+
+
+class DatasetEntryMetadata:
+    """Plain result container — kept dependency-free so routes can shape
+    the JSON response without importing pydantic into this module."""
+
+    def __init__(
+        self,
+        duration_sec: float,
+        tempo_bpm: float,
+        key: str,
+        loudness_db: float,
+        tags: list[str],
+    ) -> None:
+        self.duration_sec = duration_sec
+        self.tempo_bpm = tempo_bpm
+        self.key = key
+        self.loudness_db = loudness_db
+        self.tags = tags
+
+    def to_dict(self) -> dict:
+        return {
+            "durationSec": self.duration_sec,
+            "tempoBpm": self.tempo_bpm,
+            "key": self.key,
+            "loudnessDb": self.loudness_db,
+            "tags": self.tags,
+        }
+
+
+def analyze_for_organization(file_bytes: bytes) -> DatasetEntryMetadata:
+    """
+    Extract real acoustic metadata from an audio file for dataset tagging:
+    duration, tempo (BPM), musical key, approximate loudness, and a set of
+    auto-generated descriptive tags (tempo feel, energy level, duration
+    bucket) suitable for filtering/categorizing a growing dataset.
+    """
+    try:
+        y, sr = librosa.load(io.BytesIO(file_bytes), sr=22050, mono=True)
+    except Exception as e:
+        logger.error(f"Failed to load audio for organization: {e}", exc_info=True)
+        raise ValueError(f"Could not read audio file: {e}")
+
+    if y.size == 0 or float(np.max(np.abs(y))) < 1e-6:
+        raise ValueError("Audio file is empty or silent")
+
+    duration_sec = round(float(librosa.get_duration(y=y, sr=sr)), 2)
+
+    tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+    tempo_bpm = round(float(np.atleast_1d(tempo)[0]), 1)
+
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    key = _detect_key(np.mean(chroma, axis=1))
+
+    loudness_db = _loudness_lufs_approx(y)
+    rms_mean = float(np.mean(librosa.feature.rms(y=y)[0]))
+
+    tags = [_tempo_tag(tempo_bpm), _energy_tag(rms_mean)]
+    if duration_sec < 30:
+        tags.append("short-clip")
+    elif duration_sec > 240:
+        tags.append("long-form")
+
+    return DatasetEntryMetadata(
+        duration_sec=duration_sec,
+        tempo_bpm=tempo_bpm,
+        key=key,
+        loudness_db=loudness_db,
+        tags=tags,
+    )

tests/test_data_processing.py

@@ -5,8 +5,23 @@ from __future__ import annotations
 import io
 import json
 
+import pytest
 from fastapi.testclient import TestClient
 
+from app.routes.data_processing import _process_rate_store
+
+
+@pytest.fixture(autouse=True)
+def _reset_rate_limiter():
+    """The rate limiter's store is module-level and shared across every
+    test in this file (10 requests/60s per IP, and TestClient always uses
+    the same fake client IP) — without resetting it, tests that pass in
+    isolation start failing with 429 once enough tests run before them in
+    the same process."""
+    _process_rate_store.clear()
+    yield
+    _process_rate_store.clear()
+
 
 def _valid_options(**overrides: object) -> str:
     """Return a valid JSON options string with optional overrides."""
@@ -100,3 +115,157 @@ def test_audio_defaults_when_options_missing(client: TestClient) -> None:
     )
     # Should proceed to processing (200) or processing error — never 422
     assert response.status_code != 422
+
+
+def test_audio_rejects_oversized_file_with_413_not_500(client: TestClient) -> None:
+    """Regression test: the 413 raised inside the read loop's try block was
+    being caught by the bare `except Exception` below it (HTTPException IS
+    an Exception) and replaced with a misleading 500. A file over the 30MB
+    cap must surface as 413 file_too_large, not 500 internal_error."""
+    oversized = _fake_audio(b"\x00" * (31 * 1024 * 1024))
+    response = client.post(
+        "/api/process/audio",
+        data={"options": _valid_options()},
+        files={"file": ("big.wav", oversized, "audio/wav")},
+    )
+    assert response.status_code == 413
+    detail = response.json()["detail"]
+    assert detail["code"] == "file_too_large"
+
+
+# ─────────────────────────── /api/process/audio/convert ───────────────────────────
+
+def _valid_convert_options(**overrides: object) -> str:
+    defaults = {"targetFormat": "wav", "bitrateKbps": 192}
+    defaults.update(overrides)
+    return json.dumps(defaults)
+
+
+def test_convert_valid_request_accepted(client: TestClient) -> None:
+    """Valid audio file + valid convert options should not return 422."""
+    response = client.post(
+        "/api/process/audio/convert",
+        data={"options": _valid_convert_options()},
+        files={"file": ("test.wav", _fake_audio(), "audio/wav")},
+    )
+    assert response.status_code != 422
+
+
+def test_convert_rejects_non_audio(client: TestClient) -> None:
+    response = client.post(
+        "/api/process/audio/convert",
+        data={"options": _valid_convert_options()},
+        files={"file": ("test.txt", _fake_audio(), "text/plain")},
+    )
+    assert response.status_code == 400
+    detail = response.json()["detail"]
+    assert detail["code"] == "invalid_file_type"
+
+
+def test_convert_rejects_invalid_target_format(client: TestClient) -> None:
+    """targetFormat outside the wav/mp3/flac/ogg enum should 422."""
+    response = client.post(
+        "/api/process/audio/convert",
+        data={"options": _valid_convert_options(targetFormat="exe")},
+        files={"file": ("test.wav", _fake_audio(), "audio/wav")},
+    )
+    assert response.status_code == 422
+    detail = response.json()["detail"]
+    assert detail["code"] == "invalid_options"
+
+
+def test_convert_rejects_bitrate_out_of_range(client: TestClient) -> None:
+    response = client.post(
+        "/api/process/audio/convert",
+        data={"options": _valid_convert_options(bitrateKbps=999)},
+        files={"file": ("test.wav", _fake_audio(), "audio/wav")},
+    )
+    assert response.status_code == 422
+    detail = response.json()["detail"]
+    assert detail["code"] == "invalid_options"
+
+
+def test_convert_defaults_when_options_missing(client: TestClient) -> None:
+    """Missing options should default to wav @ 192kbps, not 422."""
+    response = client.post(
+        "/api/process/audio/convert",
+        files={"file": ("test.wav", _fake_audio(), "audio/wav")},
+    )
+    assert response.status_code != 422
+
+
+def test_convert_rejects_oversized_file_with_413_not_500(client: TestClient) -> None:
+    """Same regression as the /audio endpoint: 413 must not become 500."""
+    oversized = _fake_audio(b"\x00" * (31 * 1024 * 1024))
+    response = client.post(
+        "/api/process/audio/convert",
+        data={"options": _valid_convert_options()},
+        files={"file": ("big.wav", oversized, "audio/wav")},
+    )
+    assert response.status_code == 413
+    detail = response.json()["detail"]
+    assert detail["code"] == "file_too_large"
+
+
+# ─────────────────────────── /api/process/audio/organize ───────────────────────────
+
+def test_organize_valid_request_accepted(client: TestClient) -> None:
+    response = client.post(
+        "/api/process/audio/organize",
+        files={"file": ("test.wav", _fake_audio(), "audio/wav")},
+    )
+    # A silent all-zero WAV is a legitimate 400 (analyzer rejects silence) —
+    # never 422 (that's the "malformed request" status, not "bad content").
+    assert response.status_code != 422
+
+
+def test_organize_rejects_non_audio(client: TestClient) -> None:
+    response = client.post(
+        "/api/process/audio/organize",
+        files={"file": ("test.txt", _fake_audio(), "text/plain")},
+    )
+    assert response.status_code == 400
+    detail = response.json()["detail"]
+    assert detail["code"] == "invalid_file_type"
+
+
+def test_organize_rejects_missing_file(client: TestClient) -> None:
+    response = client.post("/api/process/audio/organize")
+    assert response.status_code == 422
+
+
+def test_organize_rejects_oversized_file_with_413(client: TestClient) -> None:
+    oversized = _fake_audio(b"\x00" * (31 * 1024 * 1024))
+    response = client.post(
+        "/api/process/audio/organize",
+        files={"file": ("big.wav", oversized, "audio/wav")},
+    )
+    assert response.status_code == 413
+    detail = response.json()["detail"]
+    assert detail["code"] == "file_too_large"
+
+
+def test_organize_returns_real_metadata_for_real_audio(client: TestClient) -> None:
+    """End-to-end with an actual sine wave — not a silent/zero fixture —
+    to prove the analyzer runs and returns genuine acoustic metadata."""
+    import io as _io
+    import numpy as _np
+    import soundfile as _sf
+
+    sr = 22050
+    t = _np.linspace(0, 2, sr * 2)
+    y = (0.4 * _np.sin(2 * _np.pi * 440 * t)).astype(_np.float32)
+    buf = _io.BytesIO()
+    _sf.write(buf, y, sr, format="WAV")
+    buf.seek(0)
+
+    response = client.post(
+        "/api/process/audio/organize",
+        files={"file": ("tone.wav", buf, "audio/wav")},
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["durationSec"] == pytest.approx(2.0, abs=0.1)
+    assert isinstance(body["tempoBpm"], (int, float))
+    assert "major" in body["key"] or "minor" in body["key"]
+    assert isinstance(body["tags"], list) and len(body["tags"]) > 0