MLflow Concepts in MotionMind Studio: Every Render Is an Experiment

Boiled down, the philosophy is four steps: never overwrite an experiment, record everything, measure the result, then choose explicitly.

Why this fits video

Making videos with an AI agent turns out to be a lot like training models.

• There are many iterations. One brief leads to several concepts, and one concept leads to several versions: a different hook, different music, 9:16 and 16:9.
• You can't predict the output from the input. The same prompt to the same agent can produce different code. What you can trust is the rendered file, not the agent's report about it.
• Some numbers have to pass. Many platforms normalise loudness to around −14 LUFS. A video that is too loud gets turned down, and one that is too quiet sounds weak next to its neighbours. For a video, loudness is a metric, just as accuracy is for a model.
• Decisions need to be remembered. The client approves version 3. Two weeks later someone asks why it wasn't version 5. Without a record, the answer is gone.

Same problem, so the solution can be borrowed.

The concept map

Here is each MLflow concept, its MotionMind counterpart and where it lives.

The sections below go through each row.

Tracking store: one folder, one source of truth

MLflow keeps runs in an mlruns/ folder or on a tracking server. MotionMind keeps them in the workspace that motionmind setup creates:

MotionMind looks for the workspace in this order: the MOTIONMIND_STORE environment variable, then the nearest folder (walking up from the current one) that contains motionmind.store.json, then ~/.motionmind.

Two small details matter when the agent and you work in the same workspace:

• registry.json is written with a lock file and an atomic rename, so two processes writing at once can't corrupt it.
• Each campaign's LOG.md is append-only. Every log, render, promotion and QA override is written there with its date and time.

Experiment → campaign

An MLflow experiment groups runs that answer the same question. In MotionMind, the question is the message: the campaign motionmind/walkthrough-30s holds every attempt to deliver one message to one audience.

The rule is simple:

• a new message or audience means a new campaign;
• a new hook, style, soundtrack or aspect ratio for the same message means a new version in the same campaign.

A campaign also keeps the context that, on an ML team, usually lives only in people's heads: TASTE.md (the style locked at Gate 2), PROGRESS.md (how far the work has got) and LOG.md. The agent reads all three before it picks the work up again, so a new chat session doesn't start from zero. Managing campaigns vs versions has examples of when to choose which.

Run → version

An MLflow run is one experiment that is never changed once it's finished. A MotionMind version works the same way: one runs/v<N>-<slug>/ folder with a run ID such as motionmind-walkthrough-30s-v2. A rendered version is never overwritten. A new direction means a new v<N+1> folder, and the skill forbids the agent from editing an old version for "a small tweak".

One thing makes a video version stronger than a typical ML run: you can open it again. Its src/ folder holds that version's HyperFrames project (HTML, CSS and GSAP), and the HyperFrames version is pinned (0.8.214 in MotionMind 0.2.0). The same source rendered with the same engine version means the result can be reproduced months later. The ML equivalent is storing the code, the environment and the seed with every run. Determinism in AI video explains why that matters.

Parameters: what was chosen

Params are the decisions that set one version apart from another. They come from three places:

1. Read automatically from the file. The aspect ratio (aspect: 9:16, 16:9 or 1:1), the safe area for 9:16 (safe_area), and for HyperFrames projects also the HyperFrames version, composition name, resolution, duration, number of scenes and composition variables.
2. Creative fields the Studio knows about: concept_name, hook_copy, cta_copy, palette, fonts, bpm and color_logic. The Studio shows them in the Registry panel, with colour swatches for the palette.
3. Anything you add with --param key=value.

A practical tip: if you want the hook to appear in the "Hook" row on the Studio's version and compare pages, use the key hook_copy, not hook. Other keys are still recorded in registry.json and show up in motionmind compare.

Metrics: what was measured

MotionMind's most important principle: metrics are measured from the file, not reported by the agent. Before it copies anything into the workspace, motionmind log runs ffprobe and ffmpeg's ebur128 filter on the video.

Loudness is measured only when the video has an audio track. You can add your own metrics with --metric key=number, such as an internal review score. But measurements always win: --metric integrated_lufs=-14 can't overwrite the measured loudness, because that is the number the QA gate reads.

There is one difference from MLflow. In MLflow a metric can have a history per step, such as the loss at every epoch. In MotionMind each version has one value per metric, because one version is one file. The history is the row of versions.

Artifacts: what was produced

Every version keeps these files:

• video.mp4 and its SHA-256 hash. The hash is also used to spot duplicates during autolog.
• contact-sheet.png: one frame per second, ten frames per row, each stamped with its time. It's the quickest way to see a whole video in one image.
• breakdown.md: a scene-by-scene note written by the agent.
• The design board from plan/design.html, if there is one.
• The src/ snapshot: the source that produced the video.

A real example: two versions, one decision

Take two mixes of the 30-second MotionMind walkthrough: a first mix that came out too loud, and a second mix after a limiter brought it to −14 LUFS. Both are logged as versions:

Notice that MotionMind warns you the moment the first version is logged: v1 is too loud (−11.2 LUFS) and its true peak is over the limit (+1.7 dBFS), so it can't go to production. motionmind compare shows what differs, and marks every differing row with ≠:

If someone tries to promote v1, the registry refuses:

Every step lands in the campaign's LOG.md:

And this is v2's entry in registry.json (trimmed):

It's plain JSON. You can read it with jq, drop it into a spreadsheet or process it with your own scripts.

The Studio: mlflow ui for renders

You can read registry.json in a terminal, but creative decisions are made by watching. So motionmind ui opens the Studio at http://127.0.0.1:4310. It listens on your own machine only and sends nothing to the cloud.

All runs. The home page shows every version as a gallery, with a summary on top: how many videos there are, how many are in production, how many videos aren't logged yet, and how many campaigns. You can filter by campaign or by status (Production, Staging, Archived, Not logged). Video thumbnails start playing when you hover over them. The order is fixed: production first, then staging, then unlogged, then archived, newest first within each group.

The version page. This is the counterpart of MLflow's run page: a player, a 4:5 safe-area overlay for 9:16 videos, a QA ✓/✗ badge, and a Registry panel with the run ID, engine, resolution, size, loudness, concept, hook, CTA, safe area, palette, source, logged time and SHA-256. Below that are the Stage panel (showing the exact QA issues when a version fails), the contact sheet, breakdown.md, the design board and the version's file list.

For 9:16 videos, the button under the player turns on the 4:5 safe-area overlay (y 285–1635), so you can see whether titles or the CTA fall behind a phone app's chrome:

Compare. Pick two versions and they play side by side, in sync: the left video is the clock, and the right one is corrected whenever it drifts by more than 1/30 of a second. Underneath is a 14-row table (stage, engine, resolution, FPS, duration, LUFS, true peak, size, concept, hook, CTA, palette, variables, source), with differing rows highlighted in amber. In MLflow you compare loss curves. Here you watch both cuts side by side with the numbers underneath.

Campaign. The campaign page shows PROGRESS.md, the last 12 lines of LOG.md, TASTE.md and all of its versions, so you can follow the story from the first version to the latest.

The Studio reads the workspace every time a page loads. There is no hidden database and no cache to go stale. If the agent has just logged a version, reload the page.

Model Registry → stages

This is the part that matters most day to day. Every version is always in one of three stages:

• staging: the default. Every new version lands here and can be reviewed.
• production: the version in use, such as the one posted to Instagram or sent to the client.
• archived: retired. It isn't deleted, just moved out of the main list.

MotionMind adds three rules that standard MLflow doesn't have.

1. Production must pass QA. For a video with audio, production requires integrated loudness of −14 LUFS ±0.5 and a true peak no higher than −1 dBFS, measured from the file. Silent videos pass, because silence is a deliberate choice. You can force a promotion with --force on the CLI or a checkbox in the Studio, but the override is written to LOG.md along with the QA issues it skipped. The skill forbids the agent from using --force unless you ask for it. Loudness standards: why −14 LUFS? explains where the number comes from.

2. One production version per aspect ratio per campaign. When a new version is promoted to production, the previous production version with the same aspect ratio moves to archived automatically. A 9:16 and a 16:9 version of the same campaign can both be in production, because they go to different places.

3. Production can't quietly break. If a production version is re-rendered and the new render fails QA, it drops back to staging, and the demotion is logged.

What if the client changes their mind? Promote the archived version back to production (it still has to pass QA). It becomes the live version again, the current one moves to the archive, and everything is logged. There is no dedicated "rollback" button, because promote already does the job.

Autolog → motionmind track

mlflow.autolog() exists because people forget to log. Video editors are no different. If you work in HyperFrames Studio, Premiere, CapCut or any other app that exports MP4, just point MotionMind at the project or export folder:

While motionmind ui or motionmind watch is running, MotionMind checks those folders every two seconds. Each new render is logged as a staging version with its measurements. A HyperFrames render is picked up once its .meta.json file says the render is complete, which also gives you the render_ms metric. A file from another editor is picked up after it has been unchanged for three seconds, so a file that is still being written isn't logged half-done. A file identical to an existing version (checked by hash) is skipped. The full guide is tracking renders from other apps.

The agent as a disciplined data scientist

On an ML team, MLflow is only useful if people actually log their runs. In MotionMind the agent does the logging, and the skill keeps it disciplined:

• "Record before you say done." The agent may not call a version done until it has been logged with motionmind log.
• Production is your call. The agent logs versions as staging and runs promote --stage production only after you approve at Gate 4.
• A new direction means a new version, not an overwritten folder.
• The edit lock is respected. While you edit a version in HyperFrames Studio, an .editing.json file tells the agent not to touch it.
• Audio fixes are driven by numbers. If the loudness is off, the agent adjusts the gain by the measured LUFS gap and renders again. No guessing.

The result is a registry that stays tidy even with dozens of versions across several chat sessions. The full flow is in the four-gate workflow.

What we deliberately didn't borrow (at least not yet)

MLflow is a big platform, and MotionMind is small on purpose. To set expectations, here is what MotionMind 0.2.0 does not have:

• Per-version tags. Not yet. Use --param or --notes for free-form labels.
• Nested runs and lineage. There is no "parent" field. A version's history comes from its number, its source field (where the file came from), its src/ snapshot and LOG.md.
• Metric charts. There are no charts. For video, two versions playing side by side turned out to be more useful than a curve.
• Free-form aliases such as "champion". There are only the three fixed stages, which so far have been enough for a client review flow.
• Deleting versions. There is no delete command. Old versions are archived, not removed.
• A shared tracking server. Everything is local. A workspace is a folder on your machine, and the Studio only listens on 127.0.0.1.

If any of these matters for your workflow, tell us on GitHub Issues.

Try it yourself

You need Node.js 22 or newer, and ffmpeg and ffprobe on your PATH.

Then, in a second terminal in the same folder, log any video you already have:

Reload the Studio and your video is there, with its measurements. If its loudness is off from −14 LUFS, you'll know straight away.

MLflow taught data scientists to stop overwriting experiments. MotionMind tries to teach the same thing to the agent that makes your videos: every render is an experiment, every experiment is recorded, and the version in use is always chosen on purpose, by you.