Music inpainting | ElevenLabs Documentation

Music inpainting is an enterprise feature. Contact sales for access.

Music inpainting allows you to modify specific sections of a song while keeping the rest unchanged. Store a generated song, then reference its sections in new composition plans to regenerate parts, extend with new intros and outros, or combine sections from multiple songs.

Quickstart

Store a song for inpainting

You can store a song for inpainting in two ways: generate a new song with store_for_inpainting, or upload an existing audio file.

Generate and store

Upload existing file

1 import os
2 from dotenv import load_dotenv
3 from elevenlabs.client import ElevenLabs
4 
5 load_dotenv()
6 elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
7 
8 # Generate a song and store it for later inpainting
9 response = elevenlabs.music.compose_detailed(
10     prompt="An upbeat pop song with verse and chorus",
11     music_length_ms=60000,
12     store_for_inpainting=True
13 )
14 song_id = response.song_id
15 
16 # Save the audio
17 with open("original.mp3", "wb") as f:
18     f.write(response.audio)

Edit a section using source_from

Reference stored sections with source_from to keep them unchanged, and omit it to regenerate:

1 # Keep the first 30 seconds, regenerate the rest with new style
2 composition_plan = {
3     "positive_global_styles": ["pop", "energetic"],
4     "negative_global_styles": [],
5     "sections": [
6         {
7             # Keep original verse (first 30 seconds)
8             "section_name": "Original Verse",
9             "duration_ms": 30000,
10             "source_from": {
11                 "song_id": song_id,
12                 "range": {"start_ms": 0, "end_ms": 30000}
13             },
14             "positive_local_styles": [],
15             "negative_local_styles": [],
16             "lines": []
17         },
18         {
19             # Regenerate chorus with new style
20             "section_name": "New Chorus",
21             "duration_ms": 30000,
22             "positive_local_styles": ["bigger drums", "layered vocals", "anthemic"],
23             "negative_local_styles": ["sparse", "minimal"],
24             "lines": ["We're rising up tonight", "Nothing can stop us now"]
25         }
26     ]
27 }
28 
29 audio = elevenlabs.music.compose(composition_plan=composition_plan)
30 
31 with open("edited.mp3", "wb") as f:
32     for chunk in audio:
33         f.write(chunk)

Negative ranges

Edit a small portion within a section using negative_ranges:

1 {
2   "section_name": "Verse with edited portion",
3   "duration_ms": 15500,
4   "source_from": {
5     "song_id": "ePfznvNUzFziFj8mRBbS",
6     "range": { "start_ms": 0, "end_ms": 15500 },
7     "negative_ranges": [{ "start_ms": 8000, "end_ms": 12000 }]
8   },
9   "positive_local_styles": ["celebratory"],
10   "negative_local_styles": [],
11   "lines": [
12     "Happy birthday to you",
13     "Happy birthday to you",
14     "Happy birthday dear Johnny",
15     "Happy birthday to you"
16   ]
17 }

This keeps seconds 0-8 and 12-15.5 from the original, regenerating only seconds 8-12.

Examples

Edit a single section

Generate a movie trailer, then regenerate just the outro with different lyrics.

Generate the original

1 composition_plan = {
2     "positive_global_styles": ["cinematic", "epic", "orchestral", "trailer"],
3     "negative_global_styles": ["acoustic", "pop", "minimalistic"],
4     "sections": [
5         {
6             "section_name": "Intro",
7             "positive_local_styles": ["low strings", "suspenseful"],
8             "negative_local_styles": [],
9             "duration_ms": 15000,
10             "lines": ["In a world beyond code", "Where sound becomes life"]
11         },
12         {
13             "section_name": "Build",
14             "positive_local_styles": ["rising brass", "full orchestra"],
15             "negative_local_styles": [],
16             "duration_ms": 20000,
17             "lines": ["Technology awakens the future", "Shaping every word into power"]
18         },
19         {
20             "section_name": "Bridge",
21             "positive_local_styles": ["ethereal choir", "crescendo"],
22             "negative_local_styles": [],
23             "duration_ms": 15000,
24             "lines": ["(ah ah ah ah)"]
25         },
26         {
27             "section_name": "Outro",
28             "positive_local_styles": ["deep narration", "epic finale"],
29             "negative_local_styles": [],
30             "duration_ms": 10000,
31             "lines": ["The voice of tomorrow, unleashed", "Elevenlabs"]
32         }
33     ]
34 }
35 
36 response = elevenlabs.music.compose_detailed(
37     composition_plan=composition_plan,
38     store_for_inpainting=True
39 )
40 song_id = response.song_id

Edit just the outro

1 from copy import deepcopy
2 
3 edited_plan = deepcopy(composition_plan)
4 
5 # Keep first 3 sections from original
6 edited_plan["sections"][0]["source_from"] = {
7     "song_id": song_id,
8     "range": {"start_ms": 0, "end_ms": 15000}
9 }
10 edited_plan["sections"][1]["source_from"] = {
11     "song_id": song_id,
12     "range": {"start_ms": 15000, "end_ms": 35000}
13 }
14 edited_plan["sections"][2]["source_from"] = {
15     "song_id": song_id,
16     "range": {"start_ms": 35000, "end_ms": 50000}
17 }
18 
19 # Change the outro lyrics (no source_from = regenerate)
20 edited_plan["sections"][3]["lines"] = ["The future has arrived", "ElevenLabs"]
21 
22 audio = elevenlabs.music.compose(composition_plan=edited_plan)

Extend a song

Add a new intro and outro to an existing song.

Generate the original

1 response = elevenlabs.music.compose_detailed(
2     prompt="Berlin night club techno",
3     music_length_ms=60000,
4     store_for_inpainting=True
5 )
6 song_id = response.song_id

Extend with new intro and outro

1 extend_plan = {
2     "positive_global_styles": [],
3     "negative_global_styles": [],
4     "sections": [
5         {
6             "section_name": "New Intro",
7             "positive_local_styles": [],
8             "negative_local_styles": [],
9             "duration_ms": 30000,
10             "lines": []
11         },
12         {
13             "section_name": "Original Core",
14             "positive_local_styles": [],
15             "negative_local_styles": [],
16             "duration_ms": 40000,
17             "source_from": {
18                 "song_id": song_id,
19                 "range": {"start_ms": 10000, "end_ms": 50000}
20             },
21             "lines": []
22         },
23         {
24             "section_name": "New Outro",
25             "positive_local_styles": [],
26             "negative_local_styles": [],
27             "duration_ms": 30000,
28             "lines": []
29         }
30     ]
31 }
32 
33 audio = elevenlabs.music.compose(composition_plan=extend_plan)

Create a seamless loop

Generate a musical phrase and create a loop using a “glue” section.

Generate a short clip

1 composition_plan = {
2     "positive_global_styles": ["acoustic guitar", "fingerpicking", "warm tone"],
3     "negative_global_styles": ["electric", "drums", "electronic"],
4     "sections": [
5         {
6             "section_name": "Solo Acoustic",
7             "positive_local_styles": ["fingerpicking", "soft dynamics"],
8             "negative_local_styles": [],
9             "duration_ms": 10000,
10             "lines": []
11         }
12     ]
13 }
14 
15 response = elevenlabs.music.compose_detailed(
16     composition_plan=composition_plan,
17     store_for_inpainting=True
18 )
19 song_id = response.song_id

Create a loop with glue section

1 loop_plan = {
2     "positive_global_styles": [],
3     "negative_global_styles": [],
4     "sections": [
5         {
6             "section_name": "Loop Start",
7             "positive_local_styles": [],
8             "negative_local_styles": [],
9             "duration_ms": 5000,
10             "source_from": {
11                 "song_id": song_id,
12                 "range": {"start_ms": 3000, "end_ms": 8000}
13             },
14             "lines": []
15         },
16         {
17             # Glue section - model generates a smooth transition
18             "section_name": "Glue",
19             "positive_local_styles": [],
20             "negative_local_styles": [],
21             "duration_ms": 3000,
22             "lines": []
23         },
24         {
25             "section_name": "Loop End",
26             "positive_local_styles": [],
27             "negative_local_styles": [],
28             "duration_ms": 5000,
29             "source_from": {
30                 "song_id": song_id,
31                 "range": {"start_ms": 3000, "end_ms": 8000}
32             },
33             "lines": []
34         }
35     ]
36 }
37 
38 audio = elevenlabs.music.compose(composition_plan=loop_plan)

Constraints

Constraint	Value
Maximum context window	5 minutes (300,000ms)
Minimum section duration	3 seconds (3,000ms)
Minimum negative range	50ms

Next steps

Composition plans

Learn composition plan fundamentals

API reference

Complete API documentation