Layer Audio Generation

Overview

Three distinct use cases with almost nothing in common: sound_effects, music, and text_to_speech. Pick one, then write the prompt the way that discipline expects. The loop and the spend gate are in the layer skill.

If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add layerai/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Sound effects

Describe the physical event, not the feeling. What object, made of what, doing what, at what scale, in what space. "Heavy oak door, iron hinges, swinging open slowly with a low groan, then a dull thud against stone" is a sound. "Scary door sound" is a mood board.

Three things decide whether a game-ready effect is usable:

The space. Generated effects arrive with room ambience baked in unless you exclude it. For an asset the engine will place in its own reverb, ask for it dry, close-mic'd, and isolated. A wet effect cannot be made dry afterwards.
The length. UI sounds are short, and a model given no length target produces a tail that has to be trimmed. State it.
One event per generation. A footstep, a sword unsheathe, and an impact are three assets. Asking for a sequence yields one file you then have to cut apart.

For UI sound sets, generate each state separately and name the shared character once in every prompt, so the confirm, cancel, and hover sounds read as one family.

Music

Name genre, instrumentation, tempo, mood, and function. Function is the one people leave out and the one that matters most: a menu loop, a combat layer, a boss intro, and a credits piece are written differently even in the same style.

Say what the track should not do. Background music for a game should not have an arresting melodic hook competing with dialogue, and stating "sparse, no lead melody, sits under voice" gets there faster than three rerolls.

Flags beat prose. Two outcomes are only guaranteed by a flag, so filter for the capability and set it on the run:

No vocals: instrumental: true (capability instrumental). "Instrumental" in the prompt is a suggestion. Set it for background music and for anything that loops.
A seamless loop: loop: true (capability loop), so the provider composes the clip to repeat. Asking for a loop in the prompt does not make one. Pair it with fixed_duration when the loop must land on an exact length, and keep the arrangement steady rather than building to a climax.

Sung words go in lyrics, separate from the prompt, with [verse] and [chorus] tags on their own lines. output_format takes only a container the model lists under output_formats; Layer never re-encodes, so asking for another fails the run.

A track with an arc

When the shape matters (quiet intro, percussion only from the second section, a swell into the boss phase), require the composition_plan capability and pass a plan instead of narrating the arc. The split is the craft: the plan's own positive_styles and negative_styles hold for the whole track (genre, era, production, palette), and each section carries only what changes there. A section's negative_styles are the only way to keep it empty of something the rest of the track has. Sections run 3 to 120 seconds, at most 30 of them, 3 seconds to 10 minutes in total.

A plan supersedes prompt, duration_seconds and instrumental, which are dropped. When the user also gave a prompt, say that it was folded into the plan's styles rather than sent.

Scoring a video

On a model reporting audio_segments, score a video stretch by stretch: each segment has a start_seconds, end_seconds and prompt, and together they must tile the scored part with no gaps and no overlaps, each end being the next start. Cut the segments on the picture's own changes.

Speech

Filter for text_to_speech. Send the script clean, with real punctuation, since models take commas and full stops as pacing. Spell out anything ambiguous: a number, an acronym, or an invented fantasy name will otherwise be read the model's way, and "Aelthyr" needs a phonetic respelling if it must be said consistently across a cast.

Direct the delivery separately from the words: pace, energy, age, accent, emotional register. Keep one voice per character and reuse the same voice selection across the project, since a voice that drifts between lines is more noticeable than one that is merely wrong.

Generate long narration in paragraph-sized chunks rather than one call. A single bad word in a four-minute take costs the whole take.

Worked example

"We need a sword-unsheathe effect for the inventory screen."

list_base_models with filter.use_case: "sound_effects". Take the first result, then get_base_model for its length and format fields.
Prompt the event: "Single steel longsword drawn from a leather scabbard, fast, bright metallic ring with a short decay. Dry, close-mic'd, isolated, no room reverb, no ambience, no music. Under one second."
estimate_forge_price, then execute with batch_size high enough to choose from, since audio runs are cheap and the take-to-take variation is large.
Poll at poll_interval_seconds, then audition the results before delivering rather than passing on the first file.

Common mistakes

Describing the emotion of a sound instead of the physical event.
Accepting baked-in reverb on an asset the engine will place in its own space.
Asking for a sequence of events in one generation, then cutting the file apart by hand.
Leaving length unstated on a UI sound.
Omitting the function of a music cue, so a background loop arrives with a lead melody.
Writing "instrumental" or "seamless loop" in the prompt instead of setting instrumental or loop.
Narrating a multi-section arc in one prompt when the model takes a composition_plan.
Sending an unpunctuated script, or an invented name with no phonetic spelling.
Generating four minutes of narration in one call.

--- name: layer-audio description: "Use when generating audio with Layer: sound effects for a game or trailer, music and background tracks, or speech and voice-over from text. Also when a sound effect comes back with unwanted ambience or reverb, when a music prompt needs structure or length control, or when choosing a voice and delivery for narration. Keywords: SFX, sound effect, foley, UI sound, music, soundtrack, loop, text to speech, TTS, voice over, narration." license: MIT --- # Layer Audio Generation ## Overview Three distinct use cases with almost nothing in common: `sound_effects`, `music`, and `text_to_speech`. Pick one, then write the prompt the way that discipline expects. The loop and the spend gate are in the `layer` skill. If a sibling skill named here is missing from your available skills, ask the user to install it (`npx skills add layerai/skills --skill <name>`); unattended, proceed from tool schemas and flag the gap. ## Sound effects Describe the physical event, not the feeling. What object, made of what, doing what, at what scale, in what space. "Heavy oak door, iron hinges, swinging open slowly with a low groan, then a dull thud against stone" is a sound. "Scary door sound" is a mood board. Three things decide whether a game-ready effect is usable: - **The space.** Generated effects arrive with room ambience baked in unless you exclude it. For an asset the engine will place in its own reverb, ask for it dry, close-mic'd, and isolated. A wet effect cannot be made dry afterwards. - **The length.** UI sounds are short, and a model given no length target produces a tail that has to be trimmed. State it. - **One event per generation.** A footstep, a sword unsheathe, and an impact are three assets. Asking for a sequence yields one file you then have to cut apart. For UI sound sets, generate each state separately and name the shared character once in every prompt, so the confirm, cancel, and hover sounds read as one family. ## Music Name genre, instrumentation, tempo, mood, and **function**. Function is the one people leave out and the one that matters most: a menu loop, a combat layer, a boss intro, and a credits piece are written differently even in the same style. Say what the track should not do. Background music for a game should not have an arresting melodic hook competing with dialogue, and stating "sparse, no lead melody, sits under voice" gets there faster than three rerolls. Flags beat prose. Two outcomes are only guaranteed by a flag, so filter for the capability and set it on the run: - **No vocals:** `instrumental: true` (capability `instrumental`). "Instrumental" in the prompt is a suggestion. Set it for background music and for anything that loops. - **A seamless loop:** `loop: true` (capability `loop`), so the provider composes the clip to repeat. Asking for a loop in the prompt does not make one. Pair it with `fixed_duration` when the loop must land on an exact length, and keep the arrangement steady rather than building to a climax. Sung words go in `lyrics`, separate from the prompt, with `[verse]` and `[chorus]` tags on their own lines. `output_format` takes only a container the model lists under `output_formats`; Layer never re-encodes, so asking for another fails the run. ### A track with an arc When the shape matters (quiet intro, percussion only from the second section, a swell into the boss phase), require the `composition_plan` capability and pass a plan instead of narrating the arc. The split is the craft: the plan's own `positive_styles` and `negative_styles` hold for the whole track (genre, era, production, palette), and each section carries only what changes there. A section's `negative_styles` are the only way to keep it empty of something the rest of the track has. Sections run 3 to 120 seconds, at most 30 of them, 3 seconds to 10 minutes in total. A plan supersedes `prompt`, `duration_seconds` and `instrumental`, which are dropped. When the user also gave a prompt, say that it was folded into the plan's styles rather than sent. ### Scoring a video On a model reporting `audio_segments`, score a video stretch by stretch: each segment has a `start_seconds`, `end_seconds` and `prompt`, and together they must tile the scored part with no gaps and no overlaps, each end being the next start. Cut the segments on the picture's own changes. ## Speech Filter for `text_to_speech`. Send the script clean, with real punctuation, since models take commas and full stops as pacing. Spell out anything ambiguous: a number, an acronym, or an invented fantasy name will otherwise be read the model's way, and "Aelthyr" needs a phonetic respelling if it must be said consistently across a cast. Direct the delivery separately from the words: pace, energy, age, accent, emotional register. Keep one voice per character and reuse the same voice selection across the project, since a voice that drifts between lines is more noticeable than one that is merely wrong. Generate long narration in paragraph-sized chunks rather than one call. A single bad word in a four-minute take costs the whole take. ## Worked example "We need a sword-unsheathe effect for the inventory screen." 1. `list_base_models` with `filter.use_case: "sound_effects"`. Take the first result, then `get_base_model` for its length and format fields. 2. Prompt the event: "Single steel longsword drawn from a leather scabbard, fast, bright metallic ring with a short decay. Dry, close-mic'd, isolated, no room reverb, no ambience, no music. Under one second." 3. `estimate_forge_price`, then execute with `batch_size` high enough to choose from, since audio runs are cheap and the take-to-take variation is large. 4. Poll at `poll_interval_seconds`, then audition the results before delivering rather than passing on the first file. ## Common mistakes - Describing the emotion of a sound instead of the physical event. - Accepting baked-in reverb on an asset the engine will place in its own space. - Asking for a sequence of events in one generation, then cutting the file apart by hand. - Leaving length unstated on a UI sound. - Omitting the function of a music cue, so a background loop arrives with a lead melody. - Writing "instrumental" or "seamless loop" in the prompt instead of setting `instrumental` or `loop`. - Narrating a multi-section arc in one prompt when the model takes a `composition_plan`. - Sending an unpunctuated script, or an invented name with no phonetic spelling. - Generating four minutes of narration in one call.

SKILL.md