> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.
# Composition plans
Composition plans provide fine-grained control over music generation, defining global styles, individual sections with local styles, and lyrics placement. Use text prompts for quick prototyping and composition plans when you need specific section structure, precise lyrics timing, or complex arrangements.
```json
{
"positive_global_styles": [
"upbeat pop",
"female vocalist with clear tone",
"polished production",
"acoustic guitar and light synths",
"uplifting energy",
"120 BPM",
"4/4 time signature",
"C major"
],
"negative_global_styles": ["dark", "aggressive", "heavy metal", "screaming", "slow tempo", "sad"],
"sections": [
{
"section_name": "Verse 1",
"positive_local_styles": [
"gentle and conversational vocals",
"acoustic guitar accompaniment",
"light drums in background",
"building anticipation"
],
"negative_local_styles": ["a cappella", "unaccompanied", "heavy"],
"duration_ms": 16000,
"lines": [
"Woke up today with a feeling inside",
"Something is changing I cannot hide",
"The sun on my face and the wind at my back",
"I'm finally ready to get on track"
]
},
{
"section_name": "Verse 2",
"positive_local_styles": [
"confident vocals",
"fuller guitar strumming",
"steady drum beat",
"bass joins in"
],
"negative_local_styles": ["a cappella", "sparse", "quiet"],
"duration_ms": 16000,
"lines": [
"Used to be scared of the world outside",
"Building up walls where I used to hide",
"But now I see clearly what I need to do",
"Take that first step into something new"
]
},
{
"section_name": "Pre-Chorus",
"positive_local_styles": [
"building intensity",
"rising synth melody",
"driving drums",
"full band playing"
],
"negative_local_styles": ["a cappella", "dropping out"],
"duration_ms": 8000,
"lines": ["No more waiting for tomorrow", "This is my time now"]
},
{
"section_name": "Chorus",
"positive_local_styles": [
"powerful and anthemic vocals",
"full band at maximum energy",
"punchy drums and bass",
"layered synths and guitar"
],
"negative_local_styles": ["a cappella", "minimal", "stripped back"],
"duration_ms": 16000,
"lines": [
"I'm breaking through",
"Nothing's gonna stop me now",
"I'm breaking through",
"Finally found out how"
]
},
{
"section_name": "Outro",
"positive_local_styles": [
"instrumental fade out",
"guitar melody repeating",
"drums softening",
"gentle ending"
],
"negative_local_styles": ["vocals", "abrupt ending", "building"],
"duration_ms": 8000,
"lines": []
}
]
}
```
Composition plans and text prompts are mutually exclusive. Use one or the other, not both.
## Quickstart
Follow the [music quickstart](/docs/eleven-api/guides/cookbooks/music) to set up your API key and install the SDK, then use composition plans for more control.
### Generate music with a composition plan
```python
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
composition_plan = {
"positive_global_styles": ["pop", "upbeat", "female vocals"],
"negative_global_styles": ["dark", "slow"],
"sections": [
{
"section_name": "Verse",
"positive_local_styles": ["soft vocals", "acoustic guitar"],
"negative_local_styles": [],
"duration_ms": 15000,
"lines": ["Walking down an empty street", "Wondering who I'll meet"]
},
{
"section_name": "Chorus",
"positive_local_styles": ["powerful vocals", "full band"],
"negative_local_styles": [],
"duration_ms": 15000,
"lines": ["This is my moment", "I won't let it go"]
}
]
}
audio = elevenlabs.music.compose(
composition_plan=composition_plan,
# with_timestamps=True, # Optional: return word-level timestamps
)
with open("output.mp3", "wb") as f:
for chunk in audio:
f.write(chunk)
```
```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
const elevenlabs = new ElevenLabsClient({
apiKey: process.env.ELEVENLABS_API_KEY,
});
const compositionPlan = {
positiveGlobalStyles: ["pop", "upbeat", "female vocals"],
negativeGlobalStyles: ["dark", "slow"],
sections: [
{
sectionName: "Verse",
positiveLocalStyles: ["soft vocals", "acoustic guitar"],
negativeLocalStyles: [],
durationMs: 15000,
lines: ["Walking down an empty street", "Wondering who I'll meet"],
},
{
sectionName: "Chorus",
positiveLocalStyles: ["powerful vocals", "full band"],
negativeLocalStyles: [],
durationMs: 15000,
lines: ["This is my moment", "I won't let it go"],
},
],
};
const audio = await elevenlabs.music.compose({
compositionPlan,
// withTimestamps: true, // Optional: return word-level timestamps
});
```
### Generate a plan from a prompt
Generate a composition plan from a text description, then modify it before generating:
```python
plan = elevenlabs.music.composition_plan.create(
prompt="An upbeat pop song about summer adventures",
music_length_ms=60000
)
# Modify the generated plan
plan["sections"][0]["lines"] = ["Custom lyrics here"]
audio = elevenlabs.music.compose(composition_plan=plan)
```
```typescript
const plan = await elevenlabs.music.compositionPlan.create({
prompt: "An upbeat pop song about summer adventures",
musicLengthMs: 60000,
});
// Modify the generated plan
plan.sections[0].lines = ["Custom lyrics here"];
const audio = await elevenlabs.music.compose({ compositionPlan: plan });
```
## Structure reference
### Global styles
Apply to the entire song:
* **positive\_global\_styles**: Genres (`"pop"`, `"rock"`), instruments (`"acoustic guitar"`, `"piano"`), mood (`"upbeat"`, `"melancholic"`), vocals (`"male vocals"`, `"female vocals"`), technical specs (`"120 BPM"`, `"A minor"`)
* **negative\_global\_styles**: What to avoid (`"dark"`, `"aggressive"`, `"electronic beats"`)
### Sections
| Field | Type | Description |
| ----------------------- | ------ | ------------------------------------------------------ |
| `section_name` | string | Name like "Verse 1", "Chorus", "Bridge" (1-100 chars) |
| `duration_ms` | number | Length in milliseconds (3,000 - 120,000) |
| `positive_local_styles` | array | Section-specific styles to include (max 50) |
| `negative_local_styles` | array | Section-specific styles to avoid (max 50) |
| `lines` | array | Lyrics for this section (max 30 lines, 200 chars each) |
A song can have up to 30 sections. Total duration must be between 3 seconds and 10 minutes, with each section between 3 and 120 seconds.
### Section duration behavior
By default, the model strictly follows the `duration_ms` values in your composition plan. Set `respect_sections_durations` to `false` for better audio quality at the cost of less precise timing:
```python
audio = elevenlabs.music.compose(
composition_plan=composition_plan,
respect_sections_durations=False # Better quality, flexible timing
)
```
```typescript
const audio = await elevenlabs.music.compose({
compositionPlan,
respectSectionsDurations: false, // Better quality, flexible timing
});
```
When set to `false`, the model still follows your section structure but adjusts timing for more natural transitions. For precise control over section boundaries, keep the default `true`.
## Writing lyrics
The `lines` field must contain only singable or speakable content. Performance directions, vocal styles, and stage directions go in `positive_local_styles`, not in lyrics.
```json title="Incorrect"
{
"lines": ["(whispered) I've been waiting", "(Man) Let's get started", "(instrumental break)"]
}
```
```json title="Correct"
{
"positive_local_styles": ["whispered vocals", "male voice"],
"lines": ["I've been waiting", "Let's get started"]
}
```
Phonetic sounds are acceptable in lyrics: `"(hmmm hmmm)"`, `"(ooh)"`, `"(yeah)"`.
For multiple vocalists, use separate sections with different `positive_local_styles` rather than annotations in lyrics.
## Style tips
Be specific with style descriptors:
```json
{
"positive_global_styles": [
"warm acoustic guitar with light fingerpicking",
"soft female vocals with intimate delivery",
"gentle percussion with brushed snare",
"80 BPM"
]
}
```
Use negative styles liberally to prevent unwanted sounds. Styles must be in English (lyrics can be any language).
If you include copyrighted content in styles, the API returns a `bad_composition_plan` error with a suggested alternative. See [handling copyrighted material](/docs/eleven-api/guides/cookbooks/music#copyrighted-material).
## Examples
### Cinematic instrumental
```json
{
"positive_global_styles": ["cinematic", "orchestral", "epic", "80 BPM", "D minor"],
"negative_global_styles": ["vocals", "lyrics", "pop", "electronic"],
"sections": [
{
"section_name": "Tension Build",
"positive_local_styles": ["low strings tremolo", "building intensity"],
"negative_local_styles": ["bright"],
"duration_ms": 15000,
"lines": []
},
{
"section_name": "Climax",
"positive_local_styles": ["full orchestra", "brass fanfare", "triumphant"],
"negative_local_styles": ["quiet"],
"duration_ms": 15000,
"lines": []
},
{
"section_name": "Resolution",
"positive_local_styles": ["gentle strings", "piano melody", "fading out"],
"negative_local_styles": ["intense"],
"duration_ms": 10000,
"lines": []
}
]
}
```
### Advertisement with voiceover
```json
{
"positive_global_styles": ["upbeat", "modern pop", "energetic", "120 BPM"],
"negative_global_styles": ["sad", "slow", "dark"],
"sections": [
{
"section_name": "Intro",
"positive_local_styles": ["instrumental", "catchy hook"],
"negative_local_styles": ["vocals"],
"duration_ms": 5000,
"lines": []
},
{
"section_name": "Voiceover",
"positive_local_styles": ["spoken voiceover", "confident male voice", "background music"],
"negative_local_styles": ["singing"],
"duration_ms": 10000,
"lines": ["Introducing the future of productivity", "Work smarter, not harder"]
},
{
"section_name": "Outro",
"positive_local_styles": ["musical sting", "memorable"],
"negative_local_styles": ["vocals"],
"duration_ms": 5000,
"lines": []
}
]
}
```
## Next steps
Get started with basic music generation
Edit and combine sections of existing songs
Complete API documentation
Best practices for music prompts