@nodetool-ai/agents 0.8.4-a24.3 → 0.8.4

package/dist/_skills/seedance-2-prompting/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: seedance-2-prompting
+description: Prompt ByteDance's Seedance 2 video line — the Subject/Motion/Environment/Look/Camera/Audio formula, how dialogue in double quotes gets voiced and lip-synced, writing the sound mix instead of leaving it open, cutting between shots in one generation, the JSON beat-sheet brief that holds an arc across a whole piece, and giving physics a consequence to chase. Use whenever the model id contains seedance-2 (bytedance/seedance-2.0 and its fast and mini variants, bytedance/seedance-2.5, kie's bytedance/seedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5, in text-to-video, image-to-video and reference-to-video form) on generate_video, animate_image, generate_video_from_references or a TextToVideo node. Not for Seedance 1.x.
+---
+
+# Seedance 2 → direct a scene, not a frame
+
+Seedance 2 writes the picture and the sound in the same pass, and that one fact
+changes the prompt. You are not describing a frame; you are directing a short
+scene including the camera move and the mix, and the model has to hold all of
+it together. It follows plain natural language, so the prompts that work read
+like a short shot brief: who, doing what, where, shot how, and what it sounds
+like.
+
+That also decides how a multi-scene piece is built: the sound belongs to the
+clip that generated it, so several Seedance clips cut together restart their
+mix at every join. `video-audio-continuity` covers when the whole piece has to
+be one generation, and the sound-design vocabulary that gets past the
+copyright filter.
+
+Reach it with `find_model` for `text_to_video` or `image_to_video`, then
+`generate_video` / `animate_image`; for the reference-to-video routes, use
+`find_model` for `reference_to_video`, then `generate_video_from_references`.
+Those forward the prompt, the media, a negative prompt (no Seedance 2 route
+has the field, so it is dropped), `duration_seconds`, the aspect ratio and the
+resolution. Audio references (`audio_urls` on fal, `reference_audios`
+elsewhere), the `generate_audio` switch and an automatic duration exist only on
+the route's own node: find it with `search_nodes`, read its fields with
+`get_node_info`, and run it with `run_node`. Each run is a paid generation,
+so confirm the scope with the user before rendering several.
+
+Pin the length from 4 to 15 seconds on 2.0, fast and mini, and up to 30 on
+2.5. An automatic length, which lets the model fit the content, is `auto` on
+fal and `-1` on AtlasCloud and Replicate; kie has none.
+
+## The formula
+
+Two parts do the work:
+
+- **Subject** — who or what is on screen, concretely.
+- **Motion** — what it is doing, and how.
+
+Everything after is optional, added as the shot needs it:
+
+- **Environment** — place, time of day, weather, light.
+- **Look** — the finished style, documentary realism through flat 2D.
+- **Camera** — framing and move, briefed the way you would brief an operator.
+- **Audio** — dialogue, ambience, score, or silence.
+
+Loaded up:
+
+> A glassblower in a leather apron pulls a glowing orange gather of molten glass
+> from the furnace, turns the rod steadily to keep it from slumping, then lifts
+> a blowpipe to his lips and breathes into it as the bulb swells and the glass
+> deepens from orange toward red. A dim workshop lit almost entirely by the
+> mouth of the furnace, tools and half-finished pieces on the bench behind him,
+> a warm documentary look with the highlights blown out slightly. The camera
+> opens on a slow push-in toward his hands, then arcs around to catch the
+> molten glass against the dark of the room. Audio: the low roar of the
+> furnace, the creak of the turning rod, a faint hiss as the surface cools, no
+> music.
+
+Every layer there is a decision the model no longer invents.
+
+## Dialogue, sound and on-screen text
+
+**Dialogue** goes in double quotes. The model voices it, matches lips to it and
+times it to the cut. Keep lines short — a long monologue drifts out of sync, so
+split a speech across two lines and let the cut carry it. Direct the delivery
+too ("play her line dry and a little proud, his quiet and worn out").
+
+**Subtitles** work by describing a voiceover and asking for the text along the
+bottom edge, timed to the voice.
+
+**Ambience** is a sound brief. Name the sounds you want in the mix, and write
+"no music" when you mean it. An open prompt comes back scored like a car advert.
+
+## Rules
+
+- **Spend words on verbs.** Motion is what gets animated. "A stunning dancer"
+  gives nothing; "a dancer dropping into a low spin, the skirt flaring, then
+  snapping upright" gives a path to follow.
+- **Use camera language.** Dolly, pan, tilt, crane, push-in, rack focus,
+  locked-off all read cleanly. "Epic cinematic camera" goes a hundred
+  directions.
+- **Under-directed audio is the common failure.** Name the diegetic sounds, the
+  room tone, and call for silence on purpose.
+- **Physics needs a consequence.** "Leaves scatter on each impact", "the mug
+  slides and tips" give the model something concrete to resolve toward.
+- **Say "cut to" when you want a cut.** Spelled out, it honours a shot list far
+  more reliably than it invents one.
+- **Two clipped lines across a cut beat one long line** that loses sync
+  halfway.
+
+The vague-versus-specific gap is the same as everywhere else, and costs more
+here because a bad clip costs seconds of render. "A beautiful cinematic video
+of a dancer, stunning, 8k, masterpiece" returns a stock dancer under flat even
+light. Set the dress, the spin, the heel strikes, the lone spotlight and the
+guitar, and the model spends its effort rendering your scene instead of
+inventing one.
+
+## Patterns
+
+- **Hard motion and real physics** — give weight and contact points: a vault
+  with a hand planted on a ledge, gravel kicking up on the landing, a jacket
+  flapping, the camera tracking alongside at chest height.
+- **A spot that cuts between shots** — "built as three cuts in one take", each
+  cut named, a title fading up on the closing frame in a named type class and
+  colour.
+- **When the sound is the scene** — a slow push-in, a naturalistic grade, and
+  a mix of droplets, a far-off bird and branch creak with "no music at all".
+- **Product hero shot** — one satisfying physical moment. A pour, a splash, a
+  tab popping with a fine spray lifting off, macro, hard rim light on the
+  droplets, then the line fading up in the lower third.
+- **Spokesperson to camera** — vertical, phone-camera look, a short spoken
+  line in quotes, a small physical beat on the last word, then a two-second
+  insert cut and back.
+
+## The structured beat sheet
+
+Prose carries one shot. For a whole piece with a shape — a hook, a turn, a
+drop, a peak — hand Seedance a JSON brief instead: global fields that hold for
+the entire clip, then a timeline of beats, each one naming its function, its
+picture and its sound. The function label (`fn`) is what keeps the model from
+flattening the arc into eight equally-weighted shots.
+
+The JSON is the prompt string, not a request body. Its `duration` and
+`negative_prompt` are text the model reads; the clip's real length still comes
+from `duration_seconds` (or the route's `duration`), so set both to match.
+
+Six global fields, then the beats:
+
+- `duration` — the whole clip, within what the endpoint you called accepts.
+  The example below runs 25 s, which only the 2.5 routes accept; on 2.0, fast
+  and mini, keep it to 15 s.
+- `camera` — one move across the whole clip, not one per beat. A single
+  continuous push-in reads as a shot; a new move every three seconds reads as
+  a montage.
+- `light` — the source, its colour temperature, and how it changes over the
+  clip. Name it once and every beat inherits it.
+- `style` — genre, lens character, grain, palette, and one or two reference
+  points for restraint.
+- `negative_prompt` — the artifacts you actually see: jitter, bent limbs,
+  morphing faces, flicker.
+- `audio_note` — the rule the mix obeys across every beat. "One continuous bed,
+  never full silence" is what stops the model resetting the sound at each cut.
+
+```json
+{
+  "duration": "25s",
+  "camera": "One continuous slow, steady push-in from extreme wide to close-up across the 25s; shallow depth by the end.",
+  "light": "Single unseen source above; cold white-cyan 6500K key casts down, intensifying steadily from a whisper to a flood; deep blue 6000K twilight ambient; hard top key, soft fill.",
+  "style": "Mysterious sci-fi first contact, withheld reveal, intimate awe; anamorphic, atmospheric haze, fine film grain, deep teal-twilight palette; Arrival / Close Encounters restraint.",
+  "negative_prompt": "Avoid jitter and bent limbs; stable facial features, no morphing, no flickering.",
+  "audio_note": "ONE continuous bed, never full silence; dips to sub-bass rumble at the DROP instead of cutting.",
+  "timeline": [
+    {"t":"0:00-0:03","fn":"Cold Open / Hook","visual":"Extreme wide, near-dark. A small child alone in a vast twilight field, tiny and still; wind begins bending the wheat toward one point, a faint unnatural tint at frame edge - source unseen.","audio":"Low sub-bass drone, faint wind, one distant detuned low-brass signal tone."},
+    {"t":"0:03-0:08","fn":"Setup / World","visual":"Medium wide. The child looks up; ordinary dusk field established as a cold light starts to rise on them from somewhere above, still unshown.","audio":"The tone bends; sparse high harmonics enter; sub-rumble slowly grows."},
+    {"t":"0:08-0:11","fn":"Inciting Incident","visual":"Medium. The 'but then': cold light intensifies on the child's face - curiosity dawning, not fear. The unseen presence is undeniable now.","audio":"First swell; a soft riser begins; a deep slow pulse enters."},
+    {"t":"0:11-0:16","fn":"Escalation / Stakes","visual":"Push-in tightening on the face. Light climbing, hair lifting, eyes widening; the child steps forward, drawn in.","audio":"Layers stack - riser rising, pulses quicken, strings enter; tension builds."},
+    {"t":"0:16-0:17","fn":"THE DROP","visual":"The hinge: everything stills for one beat, the face half-lit, breath caught, light pooled and waiting.","audio":"Bed dips to a low sub-bass rumble for one beat - near-silence, never fully out."},
+    {"t":"0:17-0:22","fn":"Climax / Emotional Peak","visual":"Close-up. PEAK: the child slowly lifts one open hand toward the light, fingers spreading; the intensifying beam washes over the small palm and reflects in wide, wonder-filled eyes as a faint slender silhouette of light enters the top edge of frame, almost meeting the fingertips.","audio":"A warm resonant swell blooms - wordless choir and vast strings soaring into awe over sustained deep brass, a fragile high motif of wonder."},
+    {"t":"0:22-0:24","fn":"Title Card","visual":"The light blooms to white across the frame; title fades in over the bloom (clean type in post).","audio":"Choir and strings resolve to one luminous sustained chord; a low sub-boom lands."},
+    {"t":"0:24-0:25","fn":"Button / Stinger","visual":"After the title, one last beat: the light settles, the field dim again; a single held stillness.","audio":"One fragile high bell tone over near-silence; hard out."}
+  ]
+}
+```
+
+What makes it work, and what to keep when you adapt it:
+
+- **Every beat has all three of `fn`, `visual` and `audio`.** A beat missing its
+  audio line is where the mix drifts back to a generic score.
+- **The drop is a beat, not a gap.** One second of the bed dipping to sub-bass
+  reads as a hinge; actual silence reads as a dropout. Say which you want.
+- **The peak beat gets the most words.** It is the only place worth spending
+  detail on a hand, a reflection, an edge of frame. The setup beats stay short.
+- **Camera and light are global, and the beats describe their state.** "Light
+  climbing, hair lifting" is a state of the global light, not a new light.
+- **Title cards belong in the timeline.** Give the bloom a beat of its own and
+  add the type in post rather than asking the model to render it.
+- **The stinger keeps the clip from ending on the peak.** One held beat after
+  the title is what makes it read as finished rather than cut off.
+
+Adapt the beat functions to the piece. A UGC ad runs hook, problem, product,
+proof, call to action; a product film runs establish, detail, transformation,
+hero, mark. The shape changes; the discipline of naming each beat's job does
+not.
+
+Grade the result with `analyze_video` and `detect_video_scenes` rather than
+watching it, and `understand_video` when you need a written read of what
+actually rendered.
+
+Adapted from fal's Seedance 2.0 prompting guide:
+https://fal.ai/learn/tools/seedance-2-0-prompting-guide

package/dist/_skills/seedream-prompting/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: seedream-prompting
+description: Prompt ByteDance's Seedream 4 and 5 image line — the six-layer brief it reads in order, the word budget past which it starts dropping clauses, quoting in-image copy and placing it, pinning what must not change before an edit, addressing references by content instead of by index, and the size to iterate at versus the size to deliver. Use whenever the model id names Seedream 4 or 5 (bytedance/seedream/v5/pro/text-to-image, bytedance/seedream/v5/lite/edit, fal-ai/bytedance/seedream/v4.5/edit, fal-ai/bytedance/seedream/v4/text-to-image, bytedance/seedream-v5.0-pro/edit, bytedance/seedream-v4.5, seedream/5-pro-image-to-image, seedream/4.5-text-to-image, bytedance/seedream-4.5) on generate_image, edit_image or a TextToImage node. Not for Seedream 3.
+---
+
+# Seedream → a production brief, not a caption
+
+Seedream rewards a brief written the way you would hand one to a retoucher:
+what the deliverable is, who is in it, where everything sits, how it is lit,
+what it says, and what it looks like. Captions get caption results.
+
+Reach it with `find_model` for `text_to_image` or `image_to_image`, then
+`generate_image` / `edit_image`. `generate_image` forwards only the prompt, a
+negative prompt, the size and a quality string, and `edit_image` only the
+images, the prompt, a negative prompt, a target size and a strength. The
+provider's own size field exists only on the route's node: find it with
+`search_nodes`, read its fields with `get_node_info`, and run it with
+`run_node`.
+
+## Six layers, in this order
+
+Earlier clauses carry more weight, so the order is part of the instruction.
+
+1. **Format** — the deliverable. "Fashion editorial magazine cover", "packshot
+   on plain white", "streaming poster".
+2. **Subject** — identity, wardrobe, materials, styling. Concrete beats
+   flattering: "a woman in her 40s, close-cropped grey hair, oversized charcoal
+   wool coat" over "a stylish woman".
+3. **Composition** — where things sit and how the frame is cut. "Subject on the
+   left vertical third, product centred at the lower edge, generous headroom".
+4. **Lighting** — direction and quality. "Hard key from camera left, deep
+   falloff, one bounce card filling the shadow side".
+5. **In-image text** — the exact copy, in quotes, with its position.
+6. **Style** — the aesthetic anchor. "Editorial photorealism, 85mm, shallow
+   focus, muted film grade".
+
+An omitted layer is a decision handed to the model's defaults, and its defaults
+are centred, evenly lit and generic.
+
+## Word budget
+
+fal's guide aims for 30–100 words on Seedream 4.x. Runware's guide says
+Seedream 5 accepts a much longer brief and starts scattering attention past
+roughly 600 English words. Specificity
+buys more than length: past the budget the model drops clauses, and which ones
+it drops is not yours to choose.
+
+## Text in the image
+
+Put the literal copy in quotation marks and say where it goes. Anything you
+describe rather than quote, the model writes for you.
+
+> Fashion editorial cover, 3:4. Masthead "ATRIUM" in tall thin capitals across
+> the top edge, one cover line "The Quiet Season" in small italics at the lower
+> left. A model in a raw-edged linen coat against a bare plaster wall, three-
+> quarter turn, looking off-frame right. Soft north light from the left, long
+> shadow across the plaster. Editorial photorealism, medium format, muted
+> palette. No other text.
+
+Closing with "no other text" is what stops the model filling the margins with
+invented lettering. Quote copy only when it belongs to the deliverable itself;
+a keyframe for a timeline or a video clip keeps its titles and supers off the
+image and gets them as text clips afterwards (`caption-titles`), where they
+stay editable.
+
+## Editing: pin before you change
+
+Reference-guided editing takes several images. fal's edit routes take up to
+ten and keep only the last ten when sent more. kie's `seedream/4.5-edit` and
+`seedream/5-lite-image-to-image` take up to 14, and kie's
+`seedream/5-pro-image-to-image` and `bytedance/seedream-v4-edit` up to 10. The
+failure mode is not the edit — it is everything you did not mention drifting. State the pins:
+
+> Change only the bottle's label to matte black with "SERIES 04" in white
+> sans-serif capitals. Keep the exact bottle silhouette, the exact camera
+> angle, the exact backdrop and the exact studio lighting from the reference.
+
+Address references by what they contain, not by position: "the tan leather
+journal", not "the second image". This differs from the "image 1 / image 2"
+convention the Qwen-Image and GPT Image guides teach; it is Seedream's own. Content descriptions survive re-ordering and
+disambiguate two references that look alike. For product identity, feed
+packshots on white — a lifestyle photo carries a scene the model will try to
+keep.
+
+Seedream 5 Pro adds region-precise editing and layer separation, which is what
+makes it the pick when one element must change and the rest of the frame must
+be provably untouched.
+
+## Size and tiers
+
+The size field differs by provider. On fal's Seedream 5 routes, `image_size`
+defaults to `auto_2K`; the Pro and Flash routes run 1024×1024 to 2048×2048
+total pixels at aspect ratios 1:16 to 16:1. fal's 4 and 4.5 routes set no
+default. AtlasCloud takes `size` (default `2048*2048`), kie `aspect_ratio` or
+`image_size`, and Replicate `size` (default `2K`). Work the composition at the smaller tier
+while you iterate and render the deliverable at 2K. Match the ratio to the
+brief rather than defaulting to square: 3:4 for a cover, 9:16 for a poster, 4:3
+for a still life.
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| Subject differs from what you described | Move the subject description earlier and make its defining features concrete |
+| An unwanted illustrative style | Name the style you want and negate the one you got explicitly |
+| Elements land in the wrong place | State spatial relationships; cut the number of things in the frame |
+| Copy is paraphrased or invented | Quote it exactly, place it, and close with "no other text" |
+| An untouched region changed in an edit | Add the pins — silhouette, angle, backdrop, lighting |
+| Clauses at the end were ignored | You are over budget; cut to the layers that matter |
+
+Grade the result with `critique_image` and `score_image_adherence` rather than
+eyeballing it, and `compare_images` when you are choosing between candidates.
+
+Adapted from fal's Seedream v4.5 prompt guide and Runware's Seedream 5.0 Pro
+prompting guide:
+https://fal.ai/learn/devs/seedream-v4-5-prompt-guide
+https://runware.ai/docs/models/bytedance-seedream-5-0-pro/guides/prompting

package/dist/_skills/short-film/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: short-film
+description: "Direct a narrative scene or short film in NodeTool with characters, dialogue, and score, and the look and cast of a story trailer. A trailer's beat structure comes from trailer-template. For product ads, use product-commercial."
+---
+
+**Load `/storyboard-core` first.** It carries the loop, the tool contract and
+the gating this skill assumes. Everything below is what narrative work adds on top.
+For a trailer or teaser, also load `/trailer-template`: it sets the eight beats, the
+drop and the title card, and this skill sets the cast, the look and the blocking.
+
+## What makes this job type its own
+
+An ad needs a board. A narrative piece needs the **screenplay framing** around it:
+title, logline, style bible, narration and a music prompt. Those live on the board's
+screenplay.
+
+Who writes which field:
+
+| Field | Headless | Board open in a tab |
+|---|---|---|
+| narration, music prompt | `edit_storyboard` → `set_board {narration, music_prompt}` | either |
+| style bible | `set_board {style}` (the board style is the style bible) | either |
+| title, logline | only through `direct_storyboard`, which writes the Director's own | `ui_storyboard_set_screenplay` |
+
+So:
+
+- Board open in a browser tab → `ui_storyboard_set_screenplay` with the whole
+  screenplay object, framing and shots together, in one call.
+- Headless → `create_storyboard`, then `set_board` with the look in `style`, the
+  premise in `brief`, and `narration` and `music_prompt`. Keep the words on each shot's
+  `dialogue` and `narration`. A title and logline of your own need the board open;
+  say so rather than pretend they were set. To have the Director write the whole
+  screenplay headless, scenes and title included, `set_setup {brief, genre}` and then
+  `direct_storyboard`.
+
+This matters at assembly: `assemble_storyboard_timeline` turns the screenplay's
+narration and music prompt into draft audio clips ready to generate.
+
+## The screenplay object
+
+```json
+{
+  "type": "screenplay",
+  "title": "Night Drop",
+  "logline": "A courier discovers the package was never meant to arrive.",
+  "brief": "40-second neo-noir teaser",
+  "styleBible": "wet asphalt, sodium and cyan, anamorphic flare, 2.39:1 crop, heavy grain",
+  "aspectRatio": "16:9",
+  "narration": "",
+  "musicPrompt": "sparse low synth pulse, one rising note at 0:32, no drums",
+  "entityIds": ["<asset id>"],
+  "shots": [
+    {
+      "slug": "1a",
+      "action": "Wide. Mara stands alone under a sodium lamp on wet asphalt, the city behind her out of focus",
+      "camera": { "framing": "wide", "lens": "40mm anamorphic", "angle": "low", "movement": "slow push" },
+      "motion": "she turns her head once toward the sound off-frame; rain falls steadily",
+      "dialogue": "",
+      "durationSeconds": 7
+    }
+  ]
+}
+```
+
+`style` is accepted as an alias of `styleBible`. Only `action` is required per shot;
+ids, indexes and statuses are filled in.
+
+## Shot pattern
+
+Six shots for forty seconds is a workable ratio — long enough to hold, few enough to
+afford. **Open wide, end close.** The wide establishes the world, the close is what the
+audience leaves with.
+
+- Give shots room: 5–8 seconds each. Narrative shots that run 2 seconds read as an ad.
+- Write blocking as physical events with counts — `she turns her head once`, `he sets
+  the case down and does not let go` — and keep emotion out of `motion`. "Tense" is
+  not a motion; a held stillness is.
+- Dialogue goes in the shot's `dialogue` field, not in `action`. That keeps the option
+  open to lift the words into a real script with
+  `extract_script_from_storyboard` and voice them per `/script-video`.
+- The style bible carries the grade. Do not restate it per shot — it is appended to
+  every still prompt already.
+
+## Casting
+
+Each character is a character entity: generate a reference, show the user, then
+`create_entity`. Add every one to the board with `set_board {entity_ids}`. A character
+seasons only the shots whose text names them, which is what you want in a scene where
+one person is alone.
+
+Recurring locations are worth a **location entity** — those apply to every shot on the
+board, which is how a single street stays the same street across six cuts.
+
+## Direct mode earns its place here
+
+Dialogue that must look synced, and heavy camera movement, both come out stiffer from
+a still. Set those shots to `render_mode: "direct"`; the direct clip prompt carries
+the camera fields, the scene lighting and the board style itself. Keep the establishing and static
+shots on `keyframe` — they are the ones where holding the look matters most.
+
+## Brief
+
+Adapt these examples to the user's brief. Example deliverables, style choices,
+and approval checkpoints apply only when the user adopts them.
+
+```
+Direct a 40-second [genre] short: [LOGLINE]. Six shots, open wide, end close,
+5-8 seconds each.
+
+Write the full framing as well as the shots: title, logline, style bible,
+aspect ratio, and a music prompt. If the board is open in a tab, set all of it
+with ui_storyboard_set_screenplay in one call; if not, set the style, narration
+and music prompt with set_board and tell me the title and logline need the tab.
+
+Cast every character as an entity from a reference you show me first, plus a
+location entity for the street. Set the shots that carry spoken lines to
+render_mode direct.
+
+If I gave no logline: a night courier loses the package. Wet asphalt, sodium and
+cyan, and she whispers "That wasn't a drop."
+
+Stop after the board. Stills before clips.
+```

package/dist/_skills/stable-audio-prompting/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: stable-audio-prompting
+description: Prompt Stability's Stable Audio line — the genre/instruments/mood/BPM order its training metadata expects, the TrackType and VocalType tags that separate music, stems and sound effects on Stable Audio 3, matching duration to what you described, which checkpoints guidance_scale and step count actually affect, and prompting the inpaint, outpaint and audio-to-audio variants where the surrounding audio outranks the prompt. Use whenever the model id names Stable Audio (fal-ai/stable-audio-25/text-to-audio, fal-ai/stable-audio-3/medium/text-to-audio, fal-ai/stable-audio-3/small/music/text-to-audio, fal-ai/stable-audio-3/small/sfx/text-to-audio, fal-ai/stable-audio-3/medium/audio-to-audio, fal-ai/stable-audio-25/inpaint, stability-ai/stable-audio-2.5) on generate_music, run_node or an audio generation node. Not for the original fal-ai/stable-audio.
+---
+
+# Stable Audio → write the metadata, not a mood
+
+Stable Audio was trained on library-music metadata, so it responds to prompts
+shaped like library-music metadata: what the genre is, what is playing, how it
+feels, how fast it goes. Poetic descriptions of a feeling get a generic bed.
+
+Reach the music endpoints with `find_model` for `text_to_music`, then
+`generate_music`, which forwards only the prompt, lyrics and a duration. Every
+dial in the table below, and the SFX checkpoints and the audio-to-audio,
+inpaint and outpaint variants, need the route's own node: find it with
+`search_nodes`, read its fields with `get_node_info`, and run it with
+`run_node`. Each run is a paid generation, so confirm the scope with the
+user before rendering several.
+
+## Music prompts
+
+Four elements, in this order:
+
+1. **Genre** — the core style, first.
+2. **Instruments** — with character, not just names. "Smooth electric piano",
+   "textural percussion", "distorted bass" carry more than "piano, drums,
+   bass".
+3. **Mood and production** — the feel, plus the production era or treatment.
+4. **BPM** — and the key when it matters.
+
+> An exciting breakbeat instrumental for a fast-paced game, funky electric
+> guitar chords, steady break drums, smooth electric piano and supporting bass.
+> Fresh, modern and adventurous, 105 BPM.
+
+Two habits that measurably help: vary the vocabulary instead of repeating the
+same adjective, and reference an era to describe production — "80s gated
+reverb", "90s grunge distortion" — which encodes a whole chain in three words.
+
+On Stable Audio 3, prefix the type. `TrackType: Music, VocalType: Instrumental`
+is the tag pair for instrumental beds and is worth setting explicitly; the
+model otherwise decides whether to bring in a vocal.
+
+## Stems and single instruments
+
+Start with `TrackType: Instrument`, then the instrument, genre, mood and BPM.
+This is the path for something that has to sit in a mix rather than be the mix.
+Playing technique, recording environment and effects all read: "close-mic'd
+upright bass, fingered, small wooden room, light tape saturation".
+
+## Sound effects
+
+`TrackType: SFX`, then three things:
+
+1. **Source** — the object or instrument making the sound.
+2. **Action** — how it is triggered, how long it rings, how it decays.
+3. **Production** — mic placement, room character, processing.
+
+> TrackType: SFX. A steel toolbox lid slamming shut on a concrete workshop
+> floor, sharp metallic impact with a short rattling decay, close mic, small
+> room with a hard early reflection.
+
+Then set a short duration. Most effects are under two seconds, and a 30-second
+request for a door slam gets you a door slam followed by 28 seconds of room.
+
+## Duration and parameters
+
+Match the duration to what you described. The Stable Audio 3 medium checkpoint
+goes to 380 seconds, but a prompt describing a loop or a hit produces its best
+result when the length fits the description; for a music bed, 60–90 seconds is
+the range the guide recommends. On a node the field changes name —
+`seconds_total` on fal's 2.5, `duration` on Stable Audio 3 and on Replicate's
+`stability-ai/stable-audio-2.5` — and 2.5 defaults to 190 seconds on both,
+which is three minutes of audio nobody asked for. `generate_music`'s
+`duration_seconds` sets it for you.
+
+| Parameter | What it does | Where to sit |
+| :--- | :--- | :--- |
+| `num_inference_steps` | Sampling steps (`steps` on Replicate) | The distilled checkpoints default to 8, and the guide says they gain little above it; raise it on a `base` checkpoint (default 50) |
+| `guidance_scale` | Prompt adherence (fal only) | The guide says it is effective on Stable Audio 3 only on `base` (non-distilled) checkpoints, which default to 7; the distilled ones default to 1 |
+| `negative_prompt` | Qualities to avoid (Stable Audio 3 only) | Name the artifact you hear: "clipping", "muddy low end", "vocal chops" |
+| `enable_prompt_expansion` | LLM prompt rewrite | Off by default; useful for a three-word prompt, harmful once your prompt is already metadata |
+| `seed` | Comparability | Pin it while you change one element at a time |
+
+The `base` versus distilled split is the one that catches people: the guide
+says that on a distilled Stable Audio 3 checkpoint the two dials most people
+reach for do little, and the prompt is the whole instrument.
+
+## Editing existing audio
+
+**Audio-to-audio** seeds generation from a clip, and the dial has two names.
+Stable Audio 3 takes `init_noise_level` (0.9 default): 0.1 keeps the source
+close, 1.0 replaces it with noise and generates outright. Stable Audio 2.5
+takes `strength` (0.8 default), which runs the same way — 0 returns the input.
+Low keeps melody and rhythm; high strips them and keeps only broad character.
+
+**Inpaint and outpaint** hold everything outside a masked region and regenerate
+inside it — `mask_start_seconds` / `mask_end_seconds` on Stable Audio 3,
+`mask_start` / `mask_end` on 2.5. Here the surrounding audio matters more than
+the prompt: a short mask is pulled hard toward its context regardless of what
+you wrote, and only a wide mask gives the prompt room. If an inpaint is
+ignoring you, widen the mask before rewriting the prompt.
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| A generic bed | Rewrite as genre, instruments with character, mood, BPM |
+| An unwanted vocal | Add `TrackType: Music, VocalType: Instrumental` to the prompt |
+| The effect is padded with room tone | Cut the duration to the length of the actual event |
+| Raising guidance changed nothing | You are probably on a distilled checkpoint — switch to `base` or fix the prompt |
+| An inpaint ignores the prompt | Widen the masked region |
+| Two takes are not comparable | Pin the seed and change one element |
+
+Check the result with `analyze_audio`, `analyze_audio_spectrum` and
+`detect_audio_events` rather than listening for it — a missing instrument or a
+clipped peak shows up there faster than by ear.
+
+## Where it lands
+
+A bed from here is the "track of your own" build in `video-audio-continuity`:
+one clip on its own audio track for the whole runtime, with the generated shots
+muted under it. Because the prompt states the BPM, `beat-sync-editing` starts
+with a grid it can predict and then confirms with `detect_audio_events` on the
+file. A `TrackType: SFX` hit of 1–3 s is what `logo-reveal` lands a mark on.
+`motion-graphics` carries the timeline ops that lay the clip down.
+
+Adapted from Stability's Stable Audio 2.5 prompt guide and the Stable Audio 3
+prompting guide:
+https://stability.ai/implementations/stable-audio-25-prompt-guide
+https://github.com/Stability-AI/stable-audio-3/blob/main/docs/guides/prompting.md