Skip to main content
osky
Submitted by Oscar Hernández on
A remix engine that can't break my session: a first look at Osky Remix Engine

A week ago this project didn't have a single line of code. Today it has an engine that analyzes a song, separates the vocal, builds a full remix, mixes it, masters it, and hands it over as an editable session for a DAW. It's called Osky Remix Engine, and this is my first review: what it is, how it's built, and what worries me.

What it is and why it exists

It's a headless, modular, non-destructive and reproducible remix production engine. Claude operates it from a CLI and I supervise through a local web UI. The README puts it plainly: the engine represents the production and Claude decides what to produce. For someone who is both a DJ and a developer, what's interesting is that every production decision is recorded and reversible.

On how it gets built: I code it together with Claude. The commits carry Co-Authored-By: Claude, and the repo's AGENTS.md sets the rules for that collaboration.

Night scene of an empty music production studio with a curved monitor showing a DAW, a MIDI keyboard, a DJ controller and studio speakers

Where it stands today

Repo numbers as of November 10, 2026:

Item Value
Commits 27, over four active days (Nov 3, 4, 8 and 9)
Python in src/ 14,411 lines
Python in tests/ 5,102 lines, 233 test functions
Frontend (React + TypeScript) a bit over 1,100 lines
Contract operations 28
Templates with content 4 (melodic_techno, melodic_techno_song, dubstep_song, reggaeton_song)

The README marks stages 0 to 6 as complete on the roadmap, with both musical milestones met: 32 bars of melodic techno with the vocal extracted from a test song, and three arrangements of the same material without losing any manual edit. After November 4 came a sample library with feature-based search, a "sound sets" system and, on November 9, song form with synced lyrics plus techno, dubstep and reggaeton styles.

And it's not just on paper: I've already tested it with nine remixes. I took three tracks (two by Los Temerarios and one by Los Yaguaru) and made each one in dubstep, reggaeton and techno. The result? It delivers: the arrangements work and the three styles are clearly different. What it's missing is detail, that layer of fine production that separates a correct remix from one I'd actually play in a set. That's where I want to push next.

The architecture

The repo splits three responsibilities, and that split is the best thing about it:

  1. Claude decides what to produce (agents/).
  2. The music engine represents the production (core/, composition/, analysis/): a canonical project with time in ticks (PPQ 960) and audio in whole samples, never floating-point seconds.
  3. The audio engine executes how it sounds (audio/, mastering/, separation/): Surge XT via DawDreamer, built-in instruments, Demucs or RoFormer for vocal separation.

Architecture diagram of the Osky Remix Engine in three columns: decides, represents and sounds

The golden rule: Claude never edits the project file. Everything goes through a contract of 28 typed operations (add_track, lock_track, move_clip, insert_time, set_automation…) applied in atomic batches. The heart of it, simplified:

for i, op in enumerate(ops):
    locked = {t.id for t in current.tracks if t.locked}
    if op.touches(current) & locked:
        raise OperationError("touches locked tracks")
    op.check(current, ctx)                      # preconditions
    draft = current.model_copy(deep=True)
    op.apply(draft)                             # on a copy
    nxt = Project.model_validate(draft.model_dump())
    op.verify(current, nxt)                     # postconditions
    current = nxt

If any operation in the batch fails, the project stays untouched and the error names the offending operation by index. Every batch that passes is stored as an immutable revision in SQLite, with parent, author (user or claude), message and hash, plus branches, merge and revert. It's Git, but for a production session.

Technical decisions worth noting

Locks the agent respects. I can lock a track from the UI and no Claude operation touches it. The agent reports the finding as "requires the user" instead of bypassing the lock. Generated content carries a provenance fingerprint: vary only regenerates what I haven't edited by hand, which is what makes milestone 2 possible.

An evaluator that measures instead of opining. The agent "listens" through master measurements: per-section energy contrast in LUFS, vocal level against the rest, bass/kick balance, masking per octave band and, with a commercial reference, tone, width, dynamics and punch. It proposes an action, renders it in memory, and only commits it if the score improves by at least 0.25; otherwise it discards it without a trace. The docs include a real run: five iterations, one discarded for not improving, and a mastering profile change at the end that brought the score to 0.

Reproducibility as an obsession. Renders are cached by full revision, resolved profile, engine, DSP versions and the hash of the Surge binary. Cache entries are immutable and jobs run in isolated processes, so a native plugin crash can't take the server down. The repo documents that many Surge presets aren't sample-exact deterministic, so each track is frozen in cache by its SHA-256.

A custom limiter. docs/COMPATIBILITY.md is a list of 19 findings, each with a name. The pedalboard limiter one is my favorite: it clipped at 0 dBFS with no lookahead or true-peak detection (+1.4 dBTP in the test), so they replaced it with one using 4× true-peak detection and lookahead. A later problem, DC offset with asymmetric kicks, got fixed with a DC blocker.

Outputs built for a DJ. extend creates a rhythm-only intro and outro in whole phrases, insert_time shifts everything as a block like "insert time" in a DAW, and cues writes Rekordbox beatgrid and cues computed from the same whole sample where the renderer places each tick. It also exports to DAWproject for Bitwig, Studio One and Cubase, and whatever can't be translated (built-in effects, sidechain, mastering) is listed in a manifest instead of silently lost.

What I like (opinion)

  • The operations contract with postconditions. It's what makes it safe to let an agent touch a production, and the decision that most separates this from "a script that generates audio".
  • Tests verify the audio, not the exit code. AGENTS.md demands it and it shows: spectral analysis is checked against pink noise with a known spectrum (error under 0.5 dB), and a reference with +6 dB in one octave yields exactly one finding in that band.
  • Honesty about limits. The docs list the DAWproject in a real DAW and the Rekordbox import as pending verification, and leave artistic approval to the user. When a measurement was badly framed, the finding gets corrected in writing instead of loosening the tolerance.
  • Blind listening. There's a tab that draws X/Y matched in loudness, stores my verdict and computes how often I agree with the evaluator (osky-remix listening). It's the right way to ask whether the metrics are any good.

What worries me (opinion)

  • The evaluator is only as good as its policy. It measures what someone decided to measure. Until blind-listening verdicts pile up, a score of 0.00 is a good sign, not proof that it sounds better. The agreement percentage that listening computes is the number I'd watch.
  • Fragile dependencies. Pins like numpy<2 and setuptools<81 (because of pkg_resources), a development version of essentia, and a comment in pyproject.toml that still calls DawDreamer a "candidate, subject to doctor". The findings also record a preset that hangs DawDreamer without using CPU. It's all documented, but this is the kind of thing that breaks on upgrade.
  • Incomplete CI. The fast test workflow runs on GitHub Actions, but the audio compatibility workflow needs a self-hosted runner that, per the docs, hasn't been set up or run. And I saw no linter or type checker configured in pyproject.toml.
  • Heuristics with fixed thresholds. song_form.py (503 lines) cuts vocal blocks after more than 6 seconds of silence, starts 0.12 s before the attack, and so on. The docs cite one verification with a real song (70 of 88 chord changes land on beat 1); I'd want more varied material before trusting the automatic form.
  • Half-built templates. afro_house, progressive_house and tech_house are folders holding a .gitkeep. Announced, but empty.
  • The UI can't see the CLI. What Claude does from the terminal doesn't show up live in the UI because it doesn't go through the server. That's documented as a limitation.

What's next

The roadmap has no stages left: everything is marked complete, so the next step is mine to define. First, the production detail the remixes are missing. Then opening the exported session in a real DAW, which is the next thing I'm testing, followed by the Rekordbox cue import, the audio runner in CI, and collecting blind-listening verdicts so the evaluator has something to compare against. More styles come after that.

Links