# SFX Desk

> Place a sound effect so its impact lands on the frame the picture does. You know
> where the hit lands; `<Audio>` wants to know where the FILE starts, and they are
> not the same number — a whoosh carries 180 ms before its transient, so `from={hitFrame}` lands the impact +180 ms late. Free browser-side engine, five paid lanes.

Live at https://sfx-desk.skillsafe.ai/ · API at https://sfx-desk.skillsafe.ai/api.html

Derived from the `add-sfx` skill in `remotion-dev/remotion`
(https://github.com/remotion-dev/remotion). Not affiliated with or endorsed by its
authors.

## The one thing to know

`startFrame = hitFrame - round(preRollMs * fps / 1000)`. At 30 fps a hit on frame 90 needs a whoosh to start on frame 85; `from={90}` puts the impact +180 ms out. A click is only +12 ms out, which is why the mistake survives — on short
effects it hides.

**Two roundings, not one.** The hit quantises to a frame and so does the pre-roll,
and they can add — so the worst case is a WHOLE frame (33.3 ms at 30 fps, 41.7 ms at 24 fps, 16.7 ms at 60 fps) rather than the 16.7 ms a single rounding gives.
A hard transient reads as out of sync past 20 ms.

**Cutting the head of a file costs level, not time.** An `<Audio>` is anchored to
the frame it is placed at, so a Sequence opening late renders it from partway in
rather than delaying it: the transient still lands on its frame and the run-up is
gone.

**The same `from` means different absolute frames in different places.** `from={24}` plays on frame 24 at the root and on frame 174 inside `body > label`.

## The inversion, in frames

| Effect | Pre-roll | In frames | Hit on frame | File starts on | `from={hitFrame}` lands | Placed properly, lands |
| --- | --- | --- | --- | --- | --- | --- |
| click | 12 ms | 0 frames | 90 | **90** | +12 ms | +12 ms |
| tick | 25 ms | 1 frame | 90 | **89** | **+25 ms** | -8.3 ms |
| thud | 45 ms | 1 frame | 90 | **89** | **+45 ms** | +11.7 ms |
| riser | 120 ms | 4 frames | 90 | **86** | **+120 ms** | -13.3 ms |
| whoosh | 180 ms | 5 frames | 90 | **85** | **+180 ms** | +13.3 ms |
| long swell | 900 ms | 27 frames | 90 | **63** | **+900 ms** | 0 ms |

At 30 fps, with the picture event on frame 90 in every row. **`from` is where the FILE starts, not where the hit lands.** The second-to-last column is what the obvious number costs; the last is what remains once the file is placed by its transient instead, which is the rounding and nothing else. Bold is past the 20 ms a hard transient allows.

## The grid against the ear

| Rate | One frame | Half a frame | A whole frame | Places a hard transient? |
| --- | --- | --- | --- | --- |
| 24 fps | 41.7 ms | 20.8 ms | 41.7 ms | **no — half a frame is already too much** |
| 25 fps | 40 ms | 20 ms | 40 ms | only if the two roundings do not add |
| 30 fps | 33.3 ms | 16.7 ms | 33.3 ms | only if the two roundings do not add |
| 48 fps | 20.8 ms | 10.4 ms | 20.8 ms | only if the two roundings do not add |
| 50 fps | 20 ms | 10 ms | 20 ms | yes |
| 60 fps | 16.7 ms | 8.3 ms | 16.7 ms | yes |

A hard transient reads as out of sync past 20 ms; a pad or a swell tolerates 60 ms. **There are two roundings, not one** — the hit time quantises to a frame and so does the pre-roll — so the column that matters is `a whole frame`, not `half a frame`. A cue quoted in FRAMES rather than in seconds has no rounding of its own and only the pre-roll's applies.

## Nesting

| Where the `<Audio>` sits | Depth | Sequence starts on | `from` | Plays on frame |
| --- | --- | --- | --- | --- |
| `root` | 1 | 0 | `from={24}` | **24** |
| `intro` | 1 | 0 | `from={24}` | **24** |
| `body` | 1 | 120 | `from={24}` | **144** |
| `body > label` | 2 | 150 | `from={24}` | **174** |

`useCurrentFrame()` is relative to the enclosing Sequence, so **nested `from` values ADD**. Every row writes the same `from={24}` and four different frames come out. Moving a cue into a Sequence therefore moves the sound, silently, and a cue sheet quoted without its nesting is half the information.

## The tail

| Effect | Length | In frames | Window | Cut | Clicks? |
| --- | --- | --- | --- | --- | --- |
| click | 90 ms | 3 frames | 60 frames | none | no |
| thud | 800 ms | 24 frames | 60 frames | none | no |
| whoosh | 1400 ms | 42 frames | 60 frames | none | no |
| long swell | 3000 ms | 90 frames | 60 frames | 30 frames (1000 ms) | **yes** |

Against a 60 frames Sequence at 30 fps. `durationInFrames` cuts the audio wherever it falls, and **a decay that stops rather than ends is a click**. Under 40 ms of tail is usually inaudible; past it, it is not.

## Constants and thresholds

| Constant | Value | What it decides |
| --- | --- | --- |
| `TRANSIENT_MS` | 20 ms | past this a hard hit reads as out of sync |
| `SOFT_MS` | 60 ms | the same limit for a pad, a swell or a riser |
| `CLICK_TAIL_MS` | 40 ms | a decay cut with more left than this clicks |
| `CEILING_DB` | 0 dBFS | overlapping cues summing past this clip |
| `NEAR_CEILING_DB` | -1 dBFS | worth naming before they do |
| `LONG_PREROLL_MS` | 100 ms | a pre-roll worth calling long |
| `RATES` | 24, 25, 30, 48, 50, 60 | the rates the sweep tries |
| `DEFAULT_FPS` | 30 fps | assumed when the sheet has no FPS |
| `DEFAULT_COMPOSITION` | 300 frames | assumed when it has no length |
| `DEFAULT_PREROLL_MS` | 0 ms | assumed when a file declares none, which is the same as assuming the file begins at its impact |
| `DEFAULT_PEAK_DB` | -6 dBFS | assumed when a file declares no peak |

Every number on this page is one of these or is derived from them. None of them is a house preference: 20 ms is where a hard transient stops reading as part of the picture, and the rest follow from the frame rate.

## Sheet grammar

A sheet is a header of `KEY: value` lines and up to three blocks.

```text
JOB: what this is                     (optional, echoed back)
FPS: 30                               (assumed 30 if absent)
COMPOSITION: 300                      (durationInFrames of the root; assumed 300)

FILES:
  <name>  preroll=<ms> dur=<ms> peak=<dBFS> kind=hard|soft

SEQUENCES:
  <name>  from=<frames> dur=<frames> in=<parent name>

CUES:
  <name>  file=<file name> hit=<time> in=<sequence name> kind=hard|soft
```

A cue's `file=` defaults to its own name, and its `in=` defaults to the root
composition. A hit time may be written `1.234s`, `1234ms`, `frame 96`, `f96`, `96f`,
`00:00:01.234` or `01:23.4`. **A bare number with a decimal point is seconds and a bare
integer is a FRAME**, because `hit=96` in a Remotion sheet means frame 96 — getting
that wrong is wrong by a factor of the frame rate, so both readings are stated back.

Anything the reader cannot place is listed as a problem rather than skipped. A sheet
whose cue lines were quietly swallowed would read as an empty composition, and every
figure on the page would be a confident answer about nothing.

## Lanes

| Lane | What it produces |
| --- | --- |
| `plan` | Turn a list of picture events into a cue sheet |
| `place` (primary) | Where every file has to start, and where every hit actually lands |
| `nest` | The nesting question: what `from` means where |
| `tail` | The window question: what the attack and the decay lose |
| `deliver` | Decide what changes: the times, the runway, or the rate |

## A worked sheet

```text
JOB: docs demo - the card lands, the label wipes on, the panel slides away
FPS: 30
COMPOSITION: 300

FILES:
  whoosh   preroll=180  dur=1400  peak=-3.0  kind=hard
  click    preroll=12   dur=90    peak=-6.0  kind=hard
  thud     preroll=45   dur=800   peak=-1.5  kind=hard

SEQUENCES:
  intro   from=0    dur=120
  body    from=120  dur=150

CUES:
  whoosh   hit=1.225s      in=intro
  click    hit=frame 96    in=intro
  thud     hit=5.41s       in=body
```

| Cue | File | In | Hit | Pre-roll | `from` | Lands | Off by | `from={hitFrame}` would be |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `whoosh` | whoosh | `intro` | frame 37 | 180 ms | **32** | frame 37.4 | **+21.7 ms** | +188.3 ms |
| `click` | click | `intro` | frame 96 | 12 ms | **96** | frame 96.36 | +12 ms | +12 ms |
| `thud` | thud | `body` | frame 162 | 45 ms | **41** | frame 162.35 | +1.7 ms | +35 ms |

The sheet in the worked example, at 30 fps over 300 frames. 3 cues at 30 fps, the obvious placement would have been +188.3 ms out, 1 outside tolerance, worst +21.7 ms. Bold is past the cue's own tolerance. Note `whoosh`: placed correctly it still misses, because the hit rounded +8.3 ms and the pre-roll rounded +13.3 ms and the two ADDED — past the 16.7 ms half a frame at this rate could give. And note `thud` on the same sheet, where they cancel instead.

## Findings

| Finding | Severity | Why it matters |
| --- | --- | --- |
| `NOTHING-TO-PLACE` | error | The sheet declares no cue |
| `THE-HIT-IS-NEVER-HEARD` | error | The transient lands outside the window entirely |
| `THE-WHOLE-ATTACK-IS-CUT` | warning | The entire attack is cut and the transient is the first thing heard |
| `THE-HIT-LANDS-OUTSIDE-TOLERANCE` | warning | A hit lands further from the picture than the ear allows |
| `THE-ATTACK-IS-CUT` | warning | The window starts after the file has to |
| `THE-FILE-MUST-START-BEFORE-FRAME-ZERO` | warning | The file has to start before the composition does |
| `THE-FROM-PROP-IS-NEGATIVE` | warning | The `from` this needs is a negative number |
| `THE-DECAY-IS-CUT` | warning | The window closes on the decay |
| `TWO-CUES-SUM-ABOVE-FULL-SCALE` | warning | Two overlapping cues sum past 0 dBFS |
| `A-CUE-NAMES-A-FILE-THE-SHEET-DOES-NOT-DECLARE` | warning | A cue names a file with no FILES entry |
| `A-CUE-NAMES-A-SEQUENCE-THE-SHEET-DOES-NOT-DECLARE` | warning | A cue names a Sequence with no SEQUENCES entry |
| `THE-SEQUENCE-TREE-HAS-A-CYCLE` | warning | A Sequence is its own ancestor |
| `A-SEQUENCE-NAMES-A-PARENT-THE-SHEET-DOES-NOT-DECLARE` | warning | A Sequence names a parent that is not declared |
| `THE-SHEET-HAS-LINES-THIS-PAGE-COULD-NOT-READ` | warning | Some lines were not readable |
| `THE-PRE-ROLL-WAS-NOT-STATED` | warning | A file declares no pre-roll |
| `A-FILE-IS-DECLARED-TWICE` | warning | Two FILES entries share a name |
| `THE-OBVIOUS-PLACEMENT-WOULD-HAVE-BEEN-LATE` | note | Writing `from={hitFrame}` would have put the hit late |
| `THE-TWO-ROUNDINGS-CANCEL` | note | On one cue the two roundings cancel |
| `THE-TWO-ROUNDINGS-ADD` | note | On one cue the two roundings add |
| `HALF-A-FRAME-IS-ALREADY-PAST-TOLERANCE` | note | At this rate one rounding is already too much |
| `ANOTHER-FRAME-RATE-WOULD-PLACE-EVERY-CUE` | note | A different rate puts every cue inside tolerance |
| `NO-FRAME-RATE-PLACES-EVERY-CUE` | note | No rate in the list places every cue |
| `A-LONG-PRE-ROLL` | note | A file has a long pre-roll |
| `A-HIT-IS-GIVEN-IN-FRAMES` | note | A hit is given in frames, so it needs no rounding |
| `A-HIT-IS-GIVEN-IN-SECONDS` | note | A hit is given in seconds, so both numbers round |
| `THE-SAME-FROM-MEANS-DIFFERENT-FRAMES` | note | Two cues share a `from` and land in different places |
| `A-CUE-SITS-IN-A-NESTED-SEQUENCE` | note | A cue is nested more than one Sequence deep |
| `A-SEQUENCE-HAS-NO-DURATION` | note | A Sequence declares no durationInFrames |
| `A-CUE-IS-OUTSIDE-THE-COMPOSITION` | note | A hit is past the end of the composition |
| `A-CUE-IS-BEFORE-THE-COMPOSITION` | note | A hit is before frame zero |
| `TWO-CUES-ON-THE-SAME-FRAME` | note | Two cues land on the same frame |
| `THE-DECAY-IS-CUT-BUT-ONLY-JUST` | note | The decay is cut, by very little |
| `TWO-CUES-SUM-NEAR-FULL-SCALE` | note | Two overlapping cues sum close to 0 dBFS |
| `EVERY-CUE-LANDS-INSIDE-TOLERANCE` | note | Every cue lands inside its tolerance |
| `THE-PEAK-WAS-NOT-STATED` | note | A file declares no peak |
| `A-FILE-IS-NEVER-CUED` | note | A declared file is never used |
| `THE-FRAME-RATE-WAS-NOT-STATED` | note | The sheet declares no FPS |
| `THE-COMPOSITION-LENGTH-WAS-NOT-STATED` | note | The sheet declares no COMPOSITION length |

38 findings: 2 errors, 14 warnings, 22 notes. Nothing that fires on every usable sheet is a warning.

## What this page cannot do

This page reads numbers, not audio. It never decodes a file, looks at a waveform or
renders anything, so:

- **Pre-roll is the one number it cannot infer.** It is the distance from the start of
  the file to its transient, and it has to come off a waveform or an editor. A sheet
  that omits it is placed as if the file began at its impact, which is the exact
  mistake this page exists to catch — so an omitted pre-roll is reported, loudly.
- **It cannot hear whether a decay cut is audible.** It reports how much tail the
  window cuts and whether that is past 40 ms. Whether that
  particular decay clicks depends on its shape at that point, which is not a number
  in a cue sheet.
- **It sums peaks, not loudness.** Two peaks adding past full scale is arithmetic; how
  loud the result seems is not, and this page does not pretend otherwise.
- **It models `<Sequence>` and `<Audio>` placement, not `playbackRate`, `volume`
  ramps, `startFrom`/`endAt` trims applied to the file itself, or anything a `<Series>`
  computes for you.** Where a sheet implies one of those, it says so rather than
  guessing.
- **20 ms is a threshold, not a cliff.** It is where a hard
  transient stops reading as part of the picture for most listeners on most material.
  A cue at 19 ms is not safe and one at 21 ms is not ruined.

## API

`POST https://api.skillsafe.ai/v1/app-api/run` with an app session token. The body
IS the input object — never wrapped in an `input` key. Fields: `task` (one of `plan`, `place`, `nest`, `tail`, `deliver`), `rules`, `prescan`, plus the lane's own fields.

`POST .../estimate` with the same body returns `hold_credits` and costs nothing.

## Provenance

Every table and every figure above is generated from `sfx.js` by `build-skill.js`.
Nothing is typed twice, so nothing can drift.