docs(compose): split compose into a group of learn and reference pages

docs.json

@@ -58,7 +58,44 @@
             "pages": [
               "jobs/ffmpeg",
               "jobs/ffprobe",
-              "jobs/compose",
+              {
+                "group": "Compose",
+                "icon": "film",
+                "expanded": true,
+                "root": "jobs/compose",
+                "pages": [
+                  "jobs/compose/timeline",
+                  "jobs/compose/framing",
+                  "jobs/compose/transitions",
+                  "jobs/compose/motion",
+                  "jobs/compose/text",
+                  "jobs/compose/fonts",
+                  "jobs/compose/shapes",
+                  "jobs/compose/effects",
+                  "jobs/compose/audio",
+                  "jobs/compose/output",
+                  "jobs/compose/craft",
+                  {
+                    "group": "Reference",
+                    "icon": "table-list",
+                    "pages": [
+                      "jobs/compose/reference/timeline",
+                      "jobs/compose/reference/video",
+                      "jobs/compose/reference/image",
+                      "jobs/compose/reference/audio",
+                      "jobs/compose/reference/text",
+                      "jobs/compose/reference/shape",
+                      "jobs/compose/reference/timer",
+                      "jobs/compose/reference/subtitles",
+                      "jobs/compose/reference/animation",
+                      "jobs/compose/reference/composition",
+                      "jobs/compose/reference/transition",
+                      "jobs/compose/reference/output",
+                      "jobs/compose/reference/effects"
+                    ]
+                  }
+                ]
+              },
               "jobs/compress",
               {
                 "group": "Captions",

jobs/compose/audio.mdx

@@ -0,0 +1,45 @@
+---
+title: "Audio levels and effects"
+sidebarTitle: "Audio"
+description: "Set levels and fades, clean up a voice recording, and draw sound onto the picture as a waveform or bars."
+icon: "waveform-lines"
+keywords: ["video audio api", "audio normalize api", "audiogram api"]
+canonical: "https://rendobar.com/docs/jobs/compose/audio"
+---
+
+Sound is a clip like any other, and a `volume` on any clip that has audio sets its level. Fades sit next to it. Everything past that is an effect on the `sound` medium, and the same effect list works on a clip or on a whole track.
+
+```json
+{
+  "asset": { "type": "audio", "src": "https://example.com/music.mp3", "volume": 0.35, "fadeIn": 1.5, "fadeOut": 2 },
+  "length": "end"
+}
+```
+
+## Levels that work
+
+
+`volume` is linear gain. With speech at 1.0: music under speech 0.10 to 0.12, music alone 0.35 to 0.5, sound effects 0.25 to 0.32. Fade music in over 1 to 2 seconds and out over 3 to 5, ending on the last frame. To duck music under speech, keep one music clip and put keyframes on its `volume`: 0.4 before the first word, 0.11 under the speech, back to 0.4 after it. `fadeIn` and `fadeOut` work alongside those keyframes.
+
+## Cleaning up a recording
+
+`loudness` brings a quiet recording to a streaming target. `voiceDenoise` removes steady background noise from under speech. `gate` closes the microphone between phrases, `highPass` cuts rumble below the voice, `eq` shapes it, and `compressor` evens out loud and quiet words.
+
+## Shaping and colour
+
+`reverb`, `echo`, `pitch`, `lowPass` and `limiter`. A limiter makes music louder without letting peaks clip.
+
+## Sound drawn on the picture
+
+`visualizer` draws the sound onto the frame for an audiogram or a podcast clip, as a waveform, bars or a level meter.
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/visualizer/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/visualizer/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="visualizer">
+    <video src="https://cdn.rendobar.com/compose/showcase/visualizer/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/visualizer/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+Every sound effect and its parameters are in the [effect reference](/docs/jobs/compose/reference/effects).

jobs/compose/craft.mdx

@@ -0,0 +1,56 @@
+---
+title: "Edit like a professional"
+sidebarTitle: "Craft"
+description: "Use the pacing, transition, text and colour conventions working editors follow, written here as compose fields."
+icon: "clapperboard"
+keywords: ["video editing best practices", "social video pacing", "video title safe area"]
+canonical: "https://rendobar.com/docs/jobs/compose/craft"
+---
+
+
+
+You do not need editing experience to get professional results. These are the conventions working editors follow, translated into compose fields. AI agents get the same rules automatically through the MCP compose reference.
+
+## Pacing
+
+
+Clip `length` is the pacing lever. Social clips run 0.8 to 3 seconds each with a visual change at least every 3 seconds, vlogs 2 to 6, tutorials 5 to 15 (cut at step boundaries), cinematic 4 to 8 with varied lengths. Shorten clips as the video builds, then hold the final shot about twice as long. The first clip is the hook: no fade-in, no logo, the payoff visible or promised within 3 seconds. A 20 to 35 second total is the highest-completion band on social.
+
+Cutting to music: seconds per beat is 60 divided by BPM. Cut every 2 or 4 beats, every beat only at the climax. For 120 BPM music that means 1 or 2 second clips.
+
+## Text placement and size
+
+
+On vertical video keep every text element inside x 8 to 92%, y 13.5 to 83% (platform UI covers the rest). Captions sit at y 60 to 75%. Sizes at 1080x1920: titles 135 to 190px, lower thirds 70 to 80px, captions 90 to 105px. Always add a stroke (black, width 4 to 8), a shadow, or a background box. Titles are 6 words or fewer, 2 lines maximum. Pair one display font (Oswald, Anton, Bebas Neue) with one body font (Inter, Roboto).
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/safe-area/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/safe-area/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="inside the safe area">
+    <video src="https://cdn.rendobar.com/compose/showcase/safe-area/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/safe-area/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+## Color looks
+
+
+Apply one look to every clip in the video:
+
+| Look | `color` value |
+| --- | --- |
+| Warm sunset | `{ "temperature": 5000, "saturation": 1.2, "contrast": 1.1 }` |
+| Cool corporate | `{ "temperature": 7500, "contrast": 1.15, "saturation": 0.95 }` |
+| Moody cinematic | `{ "temperature": 6200, "saturation": 0.75, "contrast": 1.25, "gamma": 0.92 }` |
+| Vintage faded | `{ "temperature": 5600, "contrast": 0.85, "saturation": 0.65, "brightness": 0.06 }` |
+| Bright social | `{ "temperature": 6800, "saturation": 1.3, "gamma": 1.15 }` |
+| Night | `{ "temperature": 11000, "saturation": 0.6, "gamma": 0.8, "brightness": -0.15 }` |
+
+With faces in frame stay inside saturation 0.7 to 1.3, hue within 8 degrees, temperature 4500 to 12000K. To match two clips shot differently: fix brightness first, then temperature, then saturation.
+
+## Photos need motion
+
+
+A static photo in a video reads as a mistake. Give every image clip a gentle Ken Burns move: `"transform": { "position": { "x": "50%", "y": "50%" }, "scale": [{ "time": "0%", "value": 1, "easing": "easeInOutSine" }, { "time": "100%", "value": 1.12 }] }`.
+
+Pacing and transitions have their own longer treatment on [Transitions](/docs/jobs/compose/transitions), and levels on [Audio](/docs/jobs/compose/audio).

jobs/compose/effects.mdx

@@ -0,0 +1,174 @@
+---
+title: "Picture effects"
+sidebarTitle: "Effects"
+description: "Add colour grades, looks, stylised filters and layer effects to a clip or a whole track, with keyframes on any number."
+icon: "wand-magic-sparkles"
+keywords: ["video effects api", "video color grading api", "chroma key api"]
+canonical: "https://rendobar.com/docs/jobs/compose/effects"
+---
+
+
+
+Effects are one ordered list. The same list sits on a clip, on a track, or on the whole timeline, and it runs in the order you write it.
+
+```json
+{
+  "asset": { "type": "video", "src": "https://cdn.rendobar.com/assets/examples/sea.mp4" },
+  "start": 0,
+  "length": 3,
+  "effects": [
+    { "type": "color", "saturation": 1.2, "temperature": 6800 },
+    { "type": "vignette" }
+  ]
+}
+```
+
+On a **track**, the list covers every clip on it. On the **timeline**, it covers the finished video, which is where one grade for the whole edit belongs.
+
+```json
+"timeline": {
+  "effects": [{ "type": "look", "name": "muted" }],
+  "tracks": [
+    { "effects": [{ "type": "grain" }], "clips": [{ "asset": { "type": "video", "src": "https://cdn.rendobar.com/assets/examples/sea.mp4" } }] }
+  ]
+}
+```
+
+Every entry takes an optional `start` and `length`, in seconds or as a percent of what it sits on, so an effect can run for part of a clip. Numeric parameters take keyframes, so they can move while it runs.
+
+```json
+{ "type": "blur", "radius": [{ "time": "0%", "value": 14, "easing": "easeOutCubic" }, { "time": 1, "value": 0 }] }
+```
+
+There are 34 effects, for picture and for sound, each with its own parameters in real units. The full list, with a rendered before and after for each one, is the [effects reference](https://rendobar.com/compose/effects/). The groups:
+
+| Group | Examples |
+| --- | --- |
+| Colour and looks | `color`, `look`, `lut`, `denoise`, `glow`, `grain`, `vignette`, `sharpen`, `blur` |
+| Stylise | `shake`, `glitch`, `mosaic`, `posterize`, `rgbShift`, `scanLines`, `sketch`, `trails` |
+| Layers and masking | `chromaKey`, `mask`, `blurRegion`, `outline`, `dropShadow` |
+| Sound | `eq`, `compressor`, `limiter`, `gate`, `highPass`, `lowPass`, `loudness`, `pitch`, `echo`, `reverb`, `voiceDenoise` |
+| Sound made visible | `visualizer` |
+
+Two of them read a file, which is fetched and checked like any clip source: `lut` takes a `.cube` grade, and `mask` takes a picture that decides what of the clip shows.
+
+```json
+{ "type": "mask", "src": "https://cdn.rendobar.com/assets/brand/logo-mark.png", "channel": "alpha" }
+```
+
+An effect that changes the picture is refused on a clip that has none, and one that changes the sound is refused on a silent clip, so a mistake is a 400 rather than a render that ignores it. Text and shapes draw their own outline and shadow, so `outline` and `dropShadow` are refused on them.
+
+## Colour
+
+One `color` effect carries brightness, contrast, saturation, temperature and the rest, so there is one place to correct a picture rather than nine overlapping filters. `look` applies a promoted recipe in one word, and `lut` takes a `.cube` file you supply.
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/color/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/color/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="color">
+    <video src="https://cdn.rendobar.com/compose/showcase/color/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/color/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/look/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/look/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="look">
+    <video src="https://cdn.rendobar.com/compose/showcase/look/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/look/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/lut/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/lut/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="lut">
+    <video src="https://cdn.rendobar.com/compose/showcase/lut/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/lut/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+## Stylise
+
+`glitch`, `pixelate`, `posterize`, `rgbShift`, `scanLines`, `sketch`, `trails` and `shake`. Used for a beat or a scene change rather than a whole video.
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/pixelate/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/pixelate/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="pixelate, size 24">
+    <video src="https://cdn.rendobar.com/compose/showcase/pixelate/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/pixelate/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/glitch/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/glitch/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="glitch">
+    <video src="https://cdn.rendobar.com/compose/showcase/glitch/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/glitch/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/trails/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/trails/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="trails">
+    <video src="https://cdn.rendobar.com/compose/showcase/trails/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/trails/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+## Layers
+
+`chromaKey` removes a solid background, `mask` cuts a clip to a shape, `blurRegion` hides a face or a plate, and `outline` and `dropShadow` edge a layer that has transparency.
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/chroma-key/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/chroma-key/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="chromaKey">
+    <video src="https://cdn.rendobar.com/compose/showcase/chroma-key/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/chroma-key/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/mask/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/mask/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="mask">
+    <video src="https://cdn.rendobar.com/compose/showcase/mask/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/mask/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/blur-region/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/blur-region/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="blurRegion">
+    <video src="https://cdn.rendobar.com/compose/showcase/blur-region/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/blur-region/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+<Columns cols={2}>
+  <Frame caption="before">
+    <video src="https://cdn.rendobar.com/compose/showcase/drop-shadow/before.mp4" poster="https://cdn.rendobar.com/compose/showcase/drop-shadow/before.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="dropShadow">
+    <video src="https://cdn.rendobar.com/compose/showcase/drop-shadow/after.mp4" poster="https://cdn.rendobar.com/compose/showcase/drop-shadow/after.jpg" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
+## Anything the engine can do
+
+
+`{ "type": "engine" }` reaches the rest of the render engine by its own names, for the case a promoted effect does not cover. Every service and property is checked before the job starts, so a typo is a 400 and not a failed render.
+
+```json
+{ "type": "engine", "service": "avfilter.colorize", "params": { "av.hue": 200, "av.saturation": 0.6 } }
+```
+
+An engine entry that duplicates a promoted effect is refused, so there is one way to ask for each thing. The names come from the engine and can change when it is upgraded, which the promoted names never do.
+
+Every effect and every parameter is in the [effect reference](/docs/jobs/compose/reference/effects). Sound effects are on [Audio levels and effects](/docs/jobs/compose/audio).