feat: remix ve Multitrack API uç noktaları ile rate limiting ve Pydantic schema doğrulama eklendi

app/main.py

@@ -91,7 +91,7 @@ app.add_middleware(
     allow_credentials="*" not in _origins,
     allow_methods=["GET", "POST", "OPTIONS"],
     allow_headers=["Content-Type", "Accept"],
-    expose_headers=["X-Remix-Analysis"],
+    expose_headers=["X-Remix-Analysis", "X-Multitrack-Analysis"],
 )
 
 app.include_router(health_router)

app/routes/remix.py

@@ -11,7 +11,8 @@ from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, Uplo
 from fastapi.responses import StreamingResponse
 from pydantic import ValidationError
 
-from app.schemas import RemixOptions
+from app.schemas import MultitrackAnalysis, MultitrackOptions, RemixAnalysis, RemixOptions
+from app.services.multitrack_mixer import MAX_CHANNELS, MIN_CHANNELS, mix_tracks
 from app.services.remix_engine import build_remix
 
 router = APIRouter(prefix="/api/remix", tags=["Creator Studio"])
@@ -101,7 +102,11 @@ async def remix_blend_endpoint(
 
         result = build_remix(content_a, content_b, parsed_options)
 
-        analysis_json = json.dumps(result.analysis)
+        # Serialize via the Pydantic model so the header uses the same
+        # camelCase field names the frontend's RemixAnalysis type expects —
+        # result.analysis itself is a plain snake_case dict.
+        analysis_model = RemixAnalysis(**result.analysis)
+        analysis_json = analysis_model.model_dump_json(by_alias=True)
         return StreamingResponse(
             result.audio,
             media_type="audio/wav",
@@ -118,3 +123,67 @@ async def remix_blend_endpoint(
     except Exception as e:
         logger.error(f"Unexpected error in remix blend: {e}", exc_info=True)
         raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during remix"})
+
+
+@router.post("/multitrack", dependencies=[Depends(_remix_rate_limit)])
+async def multitrack_mix_endpoint(
+    tracks: list[UploadFile] = File(...),
+    options: str = Form(default="{}"),
+):
+    """
+    Mix 2-6 uploaded tracks into one stereo WAV: applies each track's
+    gain/pan/mute, aligns lengths, sums, and peak-normalizes to prevent
+    clipping. Returns the mix plus a per-channel report in the
+    X-Multitrack-Analysis response header.
+    """
+    MAX_PAYLOAD_BYTES = 30 * 1024 * 1024  # 30 MB per track
+    logger.info(f"Received multitrack mix request: {len(tracks)} tracks")
+
+    if len(tracks) < MIN_CHANNELS or len(tracks) > MAX_CHANNELS:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "code": "invalid_track_count",
+                "message": f"Multitrack mixing requires {MIN_CHANNELS}-{MAX_CHANNELS} tracks, got {len(tracks)}.",
+            },
+        )
+
+    raw_options = options.strip() if options else "{}"
+    if not raw_options:
+        raw_options = "{}"
+    try:
+        parsed_options = MultitrackOptions.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}"})
+
+    for i, f in enumerate(tracks):
+        if not f.content_type or not f.content_type.startswith("audio/"):
+            raise HTTPException(
+                status_code=400,
+                detail={"code": "invalid_file_type", "message": f"Invalid file type for track {i + 1}. Must be audio."},
+            )
+
+    try:
+        contents = [await _read_capped(f, MAX_PAYLOAD_BYTES) for f in tracks]
+
+        result = mix_tracks(contents, parsed_options)
+
+        # Same camelCase-via-Pydantic serialization as the /blend endpoint.
+        analysis_model = MultitrackAnalysis(**result.analysis)
+        analysis_json = analysis_model.model_dump_json(by_alias=True)
+        return StreamingResponse(
+            result.audio,
+            media_type="audio/wav",
+            headers={
+                "Content-Disposition": "attachment; filename=crowncode-multitrack-mix.wav",
+                "X-Multitrack-Analysis": analysis_json,
+            },
+        )
+
+    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 multitrack mix: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail={"code": "internal_error", "message": "Internal server error during multitrack mix"})

app/schemas.py

@@ -148,3 +148,55 @@ class RemixAnalysis(BaseModel):
     applied_stretch_rate: float = Field(alias="appliedStretchRate")
     applied_pitch_shift_semitones: float = Field(alias="appliedPitchShiftSemitones")
     output_duration_sec: float = Field(alias="outputDurationSec")
+
+
+class MultitrackChannelSettings(BaseModel):
+    """Per-track mix settings for the Creator Studio Multitrack mixer.
+    Index-matched to the uploaded files (channel 0 -> first file, etc.)."""
+
+    model_config = {"populate_by_name": True}
+
+    gain_db: float = Field(
+        default=0.0, alias="gainDb", ge=-60.0, le=12.0,
+        description="Gain applied to this track before mixing, in dB"
+    )
+    pan: float = Field(
+        default=0.0, ge=-1.0, le=1.0,
+        description="Stereo position: -1.0 full left, 0.0 center, 1.0 full right"
+    )
+    muted: bool = Field(default=False, description="Exclude this track from the mix entirely")
+
+
+class MultitrackOptions(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    channels: List[MultitrackChannelSettings] = Field(
+        default_factory=list,
+        description="Per-track settings, index-matched to the uploaded files"
+    )
+    normalize_output: bool = Field(
+        default=True, alias="normalizeOutput",
+        description="Peak-normalize the final mix to prevent clipping"
+    )
+
+
+class MultitrackChannelReport(BaseModel):
+    """What actually happened to one channel during mixdown."""
+
+    model_config = {"populate_by_name": True}
+
+    index: int
+    duration_sec: float = Field(alias="durationSec")
+    applied_gain_db: float = Field(alias="appliedGainDb")
+    pan: float
+    muted: bool
+    peak_level: float = Field(alias="peakLevel")
+
+
+class MultitrackAnalysis(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    channels: List[MultitrackChannelReport]
+    output_duration_sec: float = Field(alias="outputDurationSec")
+    output_peak_level: float = Field(alias="outputPeakLevel")
+    clipping_prevented: bool = Field(alias="clippingPrevented")

app/services/multitrack_mixer.py

@@ -0,0 +1,139 @@
+"""
+Creator Studio Multitrack Mixer — real DSP, not a mock.
+
+Takes 2-6 uploaded tracks, applies per-track gain (dB) and stereo pan,
+aligns them to a common length (shorter tracks are zero-padded — silence,
+not looped, since these are independent parts of one arrangement rather
+than a loopable texture like remix_engine's crossfade blend), sums them
+into a single stereo mix, and peak-normalizes to prevent clipping.
+
+Equal-power panning (constant-power law) is used so a track panned to
+either side doesn't lose perceived loudness relative to center.
+"""
+
+import io
+import logging
+
+import librosa
+import numpy as np
+import soundfile as sf
+
+from app.schemas import MultitrackChannelSettings, MultitrackOptions
+
+logger = logging.getLogger(__name__)
+
+MAX_CHANNELS = 6
+MIN_CHANNELS = 2
+
+
+class MultitrackResult:
+    """Plain result container, mirroring RemixResult's pattern."""
+
+    def __init__(self, audio: io.BytesIO, analysis: dict) -> None:
+        self.audio = audio
+        self.analysis = analysis
+
+
+def _db_to_linear(db: float) -> float:
+    return float(10.0 ** (db / 20.0))
+
+
+def _equal_power_pan(mono: np.ndarray, pan: float) -> np.ndarray:
+    """Pan a mono signal to stereo using the constant-power law.
+    pan=-1 -> full left, 0 -> center (both channels at -3dB), 1 -> full right."""
+    angle = (pan + 1.0) * (np.pi / 4.0)  # maps [-1, 1] -> [0, pi/2]
+    left_gain = float(np.cos(angle))
+    right_gain = float(np.sin(angle))
+    stereo = np.stack([mono * left_gain, mono * right_gain], axis=1)
+    return stereo
+
+
+def mix_tracks(
+    track_bytes_list: list[bytes],
+    options: MultitrackOptions,
+) -> MultitrackResult:
+    if len(track_bytes_list) < MIN_CHANNELS:
+        raise ValueError(f"At least {MIN_CHANNELS} tracks are required for a multitrack mix")
+    if len(track_bytes_list) > MAX_CHANNELS:
+        raise ValueError(f"At most {MAX_CHANNELS} tracks are supported per mix")
+
+    channels = options.channels
+    if len(channels) != len(track_bytes_list):
+        # Missing settings default to unity gain, centered, unmuted —
+        # a caller can send fewer channel configs than files and get sane
+        # defaults for the rest rather than a validation error.
+        channels = list(channels) + [
+            MultitrackChannelSettings() for _ in range(len(track_bytes_list) - len(channels))
+        ]
+
+    sr = 22050
+    loaded: list[np.ndarray] = []
+    for i, raw in enumerate(track_bytes_list):
+        try:
+            y, _ = librosa.load(io.BytesIO(raw), sr=sr, mono=True)
+        except Exception as e:
+            logger.error(f"Failed to load track {i} for multitrack mix: {e}", exc_info=True)
+            raise ValueError(f"Could not read audio for track {i + 1}: {e}")
+        if y.size == 0:
+            raise ValueError(f"Track {i + 1} is empty")
+        loaded.append(y)
+
+    max_len = max(len(y) for y in loaded)
+    channel_reports = []
+    mix = np.zeros((max_len, 2), dtype=np.float64)
+
+    for i, (y, settings) in enumerate(zip(loaded, channels)):
+        duration_sec = round(float(len(y) / sr), 2)
+
+        if settings.muted:
+            channel_reports.append({
+                "index": i,
+                "duration_sec": duration_sec,
+                "applied_gain_db": settings.gain_db,
+                "pan": settings.pan,
+                "muted": True,
+                "peak_level": 0.0,
+            })
+            continue
+
+        # Zero-pad to common length — independent arrangement parts should
+        # not loop into each other the way a two-track crossfade blend would.
+        padded = np.pad(y, (0, max_len - len(y)))
+        gained = padded * _db_to_linear(settings.gain_db)
+        stereo = _equal_power_pan(gained, settings.pan)
+        mix += stereo
+
+        peak = float(np.max(np.abs(gained))) if gained.size else 0.0
+        channel_reports.append({
+            "index": i,
+            "duration_sec": duration_sec,
+            "applied_gain_db": settings.gain_db,
+            "pan": settings.pan,
+            "muted": False,
+            "peak_level": round(peak, 4),
+        })
+
+    output_peak = float(np.max(np.abs(mix))) if mix.size else 0.0
+    clipping_prevented = False
+    if options.normalize_output and output_peak > 1.0:
+        mix = mix / output_peak * 0.98
+        clipping_prevented = True
+        output_peak = 0.98
+    elif output_peak > 1.0:
+        # Caller explicitly disabled normalization — hard-clip rather than
+        # let soundfile silently wrap/distort on write.
+        mix = np.clip(mix, -1.0, 1.0)
+        clipping_prevented = True
+        output_peak = 1.0
+
+    out_buffer = io.BytesIO()
+    sf.write(out_buffer, mix.astype(np.float32), sr, format="WAV")
+    out_buffer.seek(0)
+
+    analysis = {
+        "channels": channel_reports,
+        "output_duration_sec": round(float(max_len / sr), 2),
+        "output_peak_level": round(output_peak, 4),
+        "clipping_prevented": clipping_prevented,
+    }
+    return MultitrackResult(audio=out_buffer, analysis=analysis)

tests/conftest.py

@@ -1,37 +1,15 @@
-"""Shared test fixtures for CrownCode backend tests.
-
-TEMPORARY isolated variant — mounts data_processing_router, dreams_router,
-remix_router, and analyze_router, bypassing the commend router's broken
-googleapiclient import chain. Restored to the original (importing the full
-app.main) immediately after this test run.
-"""
+"""Shared test fixtures for CrownCode backend tests."""
 
 from __future__ import annotations
 
 import pytest
-from fastapi import FastAPI
 from starlette.testclient import TestClient
 
-from app.routes.data_processing import router as data_processing_router
-from app.routes.dreams import router as dreams_router
-from app.routes.remix import router as remix_router
-from app.routes.analyze import router as analyze_router
-
-
-def _build_isolated_app() -> FastAPI:
-    app = FastAPI(title="CrownCode Backend API (isolated test app)")
-    app.include_router(data_processing_router)
-    app.include_router(dreams_router)
-    app.include_router(remix_router)
-    app.include_router(analyze_router)
-    return app
-
-
-_app = _build_isolated_app()
+from app.main import app
 
 
 @pytest.fixture()
 def client():
-    """Create a test client for the isolated FastAPI application."""
-    with TestClient(_app) as c:
+    """Create a test client for the FastAPI application."""
+    with TestClient(app) as c:
         yield c

tests/test_remix.py

@@ -193,3 +193,132 @@ def test_remix_blend_rate_limit(client: TestClient) -> None:
         last_status = response.status_code
 
     assert last_status == 429
+
+
+# ── Multitrack mixer tests ───────────────────────────────────────────
+
+def test_multitrack_rejects_too_few_tracks(client: TestClient) -> None:
+    response = client.post(
+        "/api/remix/multitrack",
+        files={"tracks": ("a.wav", _tone_wav(440, duration=1.0), "audio/wav")},
+    )
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_track_count"
+
+
+def test_multitrack_rejects_too_many_tracks(client: TestClient) -> None:
+    files = [
+        ("tracks", (f"t{i}.wav", _tone_wav(220 + i * 20, duration=0.5), "audio/wav"))
+        for i in range(7)
+    ]
+    response = client.post("/api/remix/multitrack", files=files)
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_track_count"
+
+
+def test_multitrack_rejects_non_audio_track(client: TestClient) -> None:
+    files = [
+        ("tracks", ("a.wav", _tone_wav(440, duration=1.0), "audio/wav")),
+        ("tracks", ("b.txt", io.BytesIO(b"not audio"), "text/plain")),
+    ]
+    response = client.post("/api/remix/multitrack", files=files)
+    assert response.status_code == 400
+    assert response.json()["detail"]["code"] == "invalid_file_type"
+
+
+def test_multitrack_rejects_invalid_options_json(client: TestClient) -> None:
+    files = [
+        ("tracks", ("a.wav", _tone_wav(440, duration=1.0), "audio/wav")),
+        ("tracks", ("b.wav", _tone_wav(330, duration=1.0), "audio/wav")),
+    ]
+    response = client.post(
+        "/api/remix/multitrack",
+        data={"options": "{not json"},
+        files=files,
+    )
+    assert response.status_code == 422
+
+
+def test_multitrack_mixes_three_tracks_and_reports_channels(client: TestClient) -> None:
+    files = [
+        ("tracks", ("a.wav", _tone_wav(220, duration=2.0), "audio/wav")),
+        ("tracks", ("b.wav", _tone_wav(330, duration=2.0), "audio/wav")),
+        ("tracks", ("c.wav", _tone_wav(440, duration=2.0), "audio/wav")),
+    ]
+    options = json.dumps({
+        "channels": [
+            {"gainDb": 0.0, "pan": -1.0, "muted": False},
+            {"gainDb": -6.0, "pan": 0.0, "muted": False},
+            {"gainDb": 0.0, "pan": 1.0, "muted": False},
+        ],
+        "normalizeOutput": True,
+    })
+    response = client.post(
+        "/api/remix/multitrack",
+        data={"options": options},
+        files=files,
+    )
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "audio/wav"
+    assert "X-Multitrack-Analysis" in response.headers
+
+    analysis = json.loads(response.headers["X-Multitrack-Analysis"])
+    channels = analysis.get("channels", [])
+    assert len(channels) == 3
+    assert all(not c["muted"] for c in channels)
+
+    # Output must be real stereo audio at the expected duration.
+    y, sr = sf.read(io.BytesIO(response.content))
+    assert y.ndim == 2 and y.shape[1] == 2
+    assert abs(len(y) / sr - 2.0) < 0.1
+
+
+def test_multitrack_muted_track_excluded_from_mix(client: TestClient) -> None:
+    """A muted track's audio must not appear in the panned-left channel."""
+    files = [
+        ("tracks", ("a.wav", _tone_wav(220, duration=1.5), "audio/wav")),
+        ("tracks", ("b.wav", _tone_wav(330, duration=1.5), "audio/wav")),
+    ]
+    options = json.dumps({
+        "channels": [
+            {"gainDb": 0.0, "pan": 0.0, "muted": True},
+            {"gainDb": 0.0, "pan": 0.0, "muted": False},
+        ],
+    })
+    response = client.post(
+        "/api/remix/multitrack",
+        data={"options": options},
+        files=files,
+    )
+    assert response.status_code == 200
+    analysis = json.loads(response.headers["X-Multitrack-Analysis"])
+    channels = analysis["channels"]
+    assert channels[0]["muted"] is True
+    assert channels[0]["peakLevel"] == 0.0
+    assert channels[1]["muted"] is False
+    assert channels[1]["peakLevel"] > 0.0
+
+
+def test_multitrack_prevents_clipping_when_normalized(client: TestClient) -> None:
+    """Six loud, centered tracks summed together would clip well past
+    1.0 without normalization — verify the output never does."""
+    files = [
+        ("tracks", (f"t{i}.wav", _tone_wav(200 + i * 50, duration=1.0), "audio/wav"))
+        for i in range(6)
+    ]
+    options = json.dumps({
+        "channels": [{"gainDb": 6.0, "pan": 0.0, "muted": False} for _ in range(6)],
+        "normalizeOutput": True,
+    })
+    response = client.post(
+        "/api/remix/multitrack",
+        data={"options": options},
+        files=files,
+    )
+    assert response.status_code == 200
+    y, sr = sf.read(io.BytesIO(response.content))
+    assert float(np.max(np.abs(y))) <= 1.0
+
+    analysis = json.loads(response.headers["X-Multitrack-Analysis"])
+    assert analysis["clippingPrevented"] is True
+    assert analysis["outputPeakLevel"] <= 1.0