TutorialsMusic

Composition plans

Precise control over music generation with structured JSON

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.

1{
2  "positive_global_styles": [
3    "upbeat pop",
4    "female vocalist with clear tone",
5    "polished production",
6    "acoustic guitar and light synths",
7    "uplifting energy",
8    "120 BPM",
9    "4/4 time signature",
10    "C major"
11  ],
12  "negative_global_styles": ["dark", "aggressive", "heavy metal", "screaming", "slow tempo", "sad"],
13  "sections": [
14    {
15      "section_name": "Verse 1",
16      "positive_local_styles": [
17        "gentle and conversational vocals",
18        "acoustic guitar accompaniment",
19        "light drums in background",
20        "building anticipation"
21      ],
22      "negative_local_styles": ["a cappella", "unaccompanied", "heavy"],
23      "duration_ms": 16000,
24      "lines": [
25        "Woke up today with a feeling inside",
26        "Something is changing I cannot hide",
27        "The sun on my face and the wind at my back",
28        "I'm finally ready to get on track"
29      ]
30    },
31    {
32      "section_name": "Verse 2",
33      "positive_local_styles": [
34        "confident vocals",
35        "fuller guitar strumming",
36        "steady drum beat",
37        "bass joins in"
38      ],
39      "negative_local_styles": ["a cappella", "sparse", "quiet"],
40      "duration_ms": 16000,
41      "lines": [
42        "Used to be scared of the world outside",
43        "Building up walls where I used to hide",
44        "But now I see clearly what I need to do",
45        "Take that first step into something new"
46      ]
47    },
48    {
49      "section_name": "Pre-Chorus",
50      "positive_local_styles": [
51        "building intensity",
52        "rising synth melody",
53        "driving drums",
54        "full band playing"
55      ],
56      "negative_local_styles": ["a cappella", "dropping out"],
57      "duration_ms": 8000,
58      "lines": ["No more waiting for tomorrow", "This is my time now"]
59    },
60    {
61      "section_name": "Chorus",
62      "positive_local_styles": [
63        "powerful and anthemic vocals",
64        "full band at maximum energy",
65        "punchy drums and bass",
66        "layered synths and guitar"
67      ],
68      "negative_local_styles": ["a cappella", "minimal", "stripped back"],
69      "duration_ms": 16000,
70      "lines": [
71        "I'm breaking through",
72        "Nothing's gonna stop me now",
73        "I'm breaking through",
74        "Finally found out how"
75      ]
76    },
77    {
78      "section_name": "Outro",
79      "positive_local_styles": [
80        "instrumental fade out",
81        "guitar melody repeating",
82        "drums softening",
83        "gentle ending"
84      ],
85      "negative_local_styles": ["vocals", "abrupt ending", "building"],
86      "duration_ms": 8000,
87      "lines": []
88    }
89  ]
90}

Composition plans and text prompts are mutually exclusive. Use one or the other, not both.

Quickstart

Follow the music quickstart to set up your API key and install the SDK, then use composition plans for more control.

1

Generate music with a composition plan

1import os
2from dotenv import load_dotenv
3from elevenlabs.client import ElevenLabs
4
5load_dotenv()
6elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
7
8composition_plan = {
9    "positive_global_styles": ["pop", "upbeat", "female vocals"],
10    "negative_global_styles": ["dark", "slow"],
11    "sections": [
12        {
13            "section_name": "Verse",
14            "positive_local_styles": ["soft vocals", "acoustic guitar"],
15            "negative_local_styles": [],
16            "duration_ms": 15000,
17            "lines": ["Walking down an empty street", "Wondering who I'll meet"]
18        },
19        {
20            "section_name": "Chorus",
21            "positive_local_styles": ["powerful vocals", "full band"],
22            "negative_local_styles": [],
23            "duration_ms": 15000,
24            "lines": ["This is my moment", "I won't let it go"]
25        }
26    ]
27}
28
29audio = elevenlabs.music.compose(
30    composition_plan=composition_plan,
31    # with_timestamps=True,  # Optional: return word-level timestamps
32)
33
34with open("output.mp3", "wb") as f:
35    for chunk in audio:
36        f.write(chunk)
2

Generate a plan from a prompt

Generate a composition plan from a text description, then modify it before generating:

1plan = elevenlabs.music.composition_plan.create(
2    prompt="An upbeat pop song about summer adventures",
3    music_length_ms=60000
4)
5
6# Modify the generated plan
7plan["sections"][0]["lines"] = ["Custom lyrics here"]
8
9audio = elevenlabs.music.compose(composition_plan=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

FieldTypeDescription
section_namestringName like “Verse 1”, “Chorus”, “Bridge” (1-100 chars)
duration_msnumberLength in milliseconds (3,000 - 120,000)
positive_local_stylesarraySection-specific styles to include (max 50)
negative_local_stylesarraySection-specific styles to avoid (max 50)
linesarrayLyrics 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:

1audio = elevenlabs.music.compose(
2    composition_plan=composition_plan,
3    respect_sections_durations=False  # Better quality, flexible timing
4)

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.

1{
2  "lines": ["(whispered) I've been waiting", "(Man) Let's get started", "(instrumental break)"]
3}

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:

1{
2  "positive_global_styles": [
3    "warm acoustic guitar with light fingerpicking",
4    "soft female vocals with intimate delivery",
5    "gentle percussion with brushed snare",
6    "80 BPM"
7  ]
8}

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.

Examples

Cinematic instrumental

1{
2  "positive_global_styles": ["cinematic", "orchestral", "epic", "80 BPM", "D minor"],
3  "negative_global_styles": ["vocals", "lyrics", "pop", "electronic"],
4  "sections": [
5    {
6      "section_name": "Tension Build",
7      "positive_local_styles": ["low strings tremolo", "building intensity"],
8      "negative_local_styles": ["bright"],
9      "duration_ms": 15000,
10      "lines": []
11    },
12    {
13      "section_name": "Climax",
14      "positive_local_styles": ["full orchestra", "brass fanfare", "triumphant"],
15      "negative_local_styles": ["quiet"],
16      "duration_ms": 15000,
17      "lines": []
18    },
19    {
20      "section_name": "Resolution",
21      "positive_local_styles": ["gentle strings", "piano melody", "fading out"],
22      "negative_local_styles": ["intense"],
23      "duration_ms": 10000,
24      "lines": []
25    }
26  ]
27}
1{
2  "positive_global_styles": ["upbeat", "modern pop", "energetic", "120 BPM"],
3  "negative_global_styles": ["sad", "slow", "dark"],
4  "sections": [
5    {
6      "section_name": "Intro",
7      "positive_local_styles": ["instrumental", "catchy hook"],
8      "negative_local_styles": ["vocals"],
9      "duration_ms": 5000,
10      "lines": []
11    },
12    {
13      "section_name": "Voiceover",
14      "positive_local_styles": ["spoken voiceover", "confident male voice", "background music"],
15      "negative_local_styles": ["singing"],
16      "duration_ms": 10000,
17      "lines": ["Introducing the future of productivity", "Work smarter, not harder"]
18    },
19    {
20      "section_name": "Outro",
21      "positive_local_styles": ["musical sting", "memorable"],
22      "negative_local_styles": ["vocals"],
23      "duration_ms": 5000,
24      "lines": []
25    }
26  ]
27}

Next steps

Music quickstart

Get started with basic music generation

Music inpainting

Edit and combine sections of existing songs

API reference

Complete API documentation

Prompting guide

Best practices for music prompts