> 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.

# Music inpainting

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.

```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"))

# Generate a song and store it for later inpainting
response = elevenlabs.music.compose_detailed(
    prompt="An upbeat pop song with verse and chorus",
    music_length_ms=60000,
    store_for_inpainting=True
)
song_id = response.song_id

# Save the audio
with open("original.mp3", "wb") as f:
    f.write(response.audio)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

const response = await elevenlabs.music.composeDetailed({
  prompt: "An upbeat pop song with verse and chorus",
  musicLengthMs: 60000,
  storeForInpainting: true,
});
const songId = response.songId;
```

```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"))

# Upload an existing audio file for inpainting
response = elevenlabs.music.upload(
    file=open("my-song.mp3", "rb"),
    extract_composition_plan=True  # Optional: extract the composition plan
)
song_id = response.song_id
composition_plan = response.composition_plan  # None if extract_composition_plan is False
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import fs from "fs";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

const response = await elevenlabs.music.upload({
  file: fs.createReadStream("my-song.mp3"),
  extractCompositionPlan: true, // Optional: extract the composition plan
});
const songId = response.songId;
const compositionPlan = response.compositionPlan; // undefined if extractCompositionPlan is false
```

### Edit a section using source\_from

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

```python
# Keep the first 30 seconds, regenerate the rest with new style
composition_plan = {
    "positive_global_styles": ["pop", "energetic"],
    "negative_global_styles": [],
    "sections": [
        {
            # Keep original verse (first 30 seconds)
            "section_name": "Original Verse",
            "duration_ms": 30000,
            "source_from": {
                "song_id": song_id,
                "range": {"start_ms": 0, "end_ms": 30000}
            },
            "positive_local_styles": [],
            "negative_local_styles": [],
            "lines": []
        },
        {
            # Regenerate chorus with new style
            "section_name": "New Chorus",
            "duration_ms": 30000,
            "positive_local_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_local_styles": ["sparse", "minimal"],
            "lines": ["We're rising up tonight", "Nothing can stop us now"]
        }
    ]
}

audio = elevenlabs.music.compose(composition_plan=composition_plan)

with open("edited.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)
```

```typescript
// Keep the first 30 seconds, regenerate the rest with new style
const compositionPlan = {
  positiveGlobalStyles: ["pop", "energetic"],
  negativeGlobalStyles: [],
  sections: [
    {
      // Keep original verse (first 30 seconds)
      sectionName: "Original Verse",
      durationMs: 30000,
      sourceFrom: {
        songId,
        range: { startMs: 0, endMs: 30000 },
      },
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      lines: [],
    },
    {
      // Regenerate chorus with new style
      sectionName: "New Chorus",
      durationMs: 30000,
      positiveLocalStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeLocalStyles: ["sparse", "minimal"],
      lines: ["We're rising up tonight", "Nothing can stop us now"],
    },
  ],
};

const audio = await elevenlabs.music.compose({ compositionPlan });
```

## Negative ranges

Edit a small portion within a section using `negative_ranges`:

```json
{
  "section_name": "Verse with edited portion",
  "duration_ms": 15500,
  "source_from": {
    "song_id": "ePfznvNUzFziFj8mRBbS",
    "range": { "start_ms": 0, "end_ms": 15500 },
    "negative_ranges": [{ "start_ms": 8000, "end_ms": 12000 }]
  },
  "positive_local_styles": ["celebratory"],
  "negative_local_styles": [],
  "lines": [
    "Happy birthday to you",
    "Happy birthday to you",
    "Happy birthday dear Johnny",
    "Happy birthday to you"
  ]
}
```

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

```python
composition_plan = {
    "positive_global_styles": ["cinematic", "epic", "orchestral", "trailer"],
    "negative_global_styles": ["acoustic", "pop", "minimalistic"],
    "sections": [
        {
            "section_name": "Intro",
            "positive_local_styles": ["low strings", "suspenseful"],
            "negative_local_styles": [],
            "duration_ms": 15000,
            "lines": ["In a world beyond code", "Where sound becomes life"]
        },
        {
            "section_name": "Build",
            "positive_local_styles": ["rising brass", "full orchestra"],
            "negative_local_styles": [],
            "duration_ms": 20000,
            "lines": ["Technology awakens the future", "Shaping every word into power"]
        },
        {
            "section_name": "Bridge",
            "positive_local_styles": ["ethereal choir", "crescendo"],
            "negative_local_styles": [],
            "duration_ms": 15000,
            "lines": ["(ah ah ah ah)"]
        },
        {
            "section_name": "Outro",
            "positive_local_styles": ["deep narration", "epic finale"],
            "negative_local_styles": [],
            "duration_ms": 10000,
            "lines": ["The voice of tomorrow, unleashed", "Elevenlabs"]
        }
    ]
}

response = elevenlabs.music.compose_detailed(
    composition_plan=composition_plan,
    store_for_inpainting=True
)
song_id = response.song_id
```

```typescript
const compositionPlan = {
  positiveGlobalStyles: ["cinematic", "epic", "orchestral", "trailer"],
  negativeGlobalStyles: ["acoustic", "pop", "minimalistic"],
  sections: [
    {
      sectionName: "Intro",
      positiveLocalStyles: ["low strings", "suspenseful"],
      negativeLocalStyles: [],
      durationMs: 15000,
      lines: ["In a world beyond code", "Where sound becomes life"],
    },
    {
      sectionName: "Build",
      positiveLocalStyles: ["rising brass", "full orchestra"],
      negativeLocalStyles: [],
      durationMs: 20000,
      lines: ["Technology awakens the future", "Shaping every word into power"],
    },
    {
      sectionName: "Bridge",
      positiveLocalStyles: ["ethereal choir", "crescendo"],
      negativeLocalStyles: [],
      durationMs: 15000,
      lines: ["(ah ah ah ah)"],
    },
    {
      sectionName: "Outro",
      positiveLocalStyles: ["deep narration", "epic finale"],
      negativeLocalStyles: [],
      durationMs: 10000,
      lines: ["The voice of tomorrow", "Unleashed"],
    },
  ],
};

const response = await elevenlabs.music.composeDetailed({
  compositionPlan,
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original Movie Trailer" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer.mp3" />

### Edit just the outro

```python
from copy import deepcopy

edited_plan = deepcopy(composition_plan)

# Keep first 3 sections from original
edited_plan["sections"][0]["source_from"] = {
    "song_id": song_id,
    "range": {"start_ms": 0, "end_ms": 15000}
}
edited_plan["sections"][1]["source_from"] = {
    "song_id": song_id,
    "range": {"start_ms": 15000, "end_ms": 35000}
}
edited_plan["sections"][2]["source_from"] = {
    "song_id": song_id,
    "range": {"start_ms": 35000, "end_ms": 50000}
}

# Change the outro lyrics (no source_from = regenerate)
edited_plan["sections"][3]["lines"] = ["The future has arrived", "ElevenLabs"]

audio = elevenlabs.music.compose(composition_plan=edited_plan)
```

```typescript
// Keep first 3 sections from original
const editedPlan = {
  ...compositionPlan,
  sections: [
    {
      ...compositionPlan.sections[0],
      sourceFrom: { songId, range: { startMs: 0, endMs: 15000 } },
    },
    {
      ...compositionPlan.sections[1],
      sourceFrom: { songId, range: { startMs: 15000, endMs: 35000 } },
    },
    {
      ...compositionPlan.sections[2],
      sourceFrom: { songId, range: { startMs: 35000, endMs: 50000 } },
    },
    {
      // Change the outro lyrics (no sourceFrom = regenerate)
      ...compositionPlan.sections[3],
      lines: ["The future has arrived", "Elevenlabs"],
    },
  ],
};

const audio = await elevenlabs.music.compose({ compositionPlan: editedPlan });
```

<elevenlabs-audio-player audio-title="Edited Outro" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer_edited.mp3" />

### Extend a song

Add a new intro and outro to an existing song.

### Generate the original

```python
response = elevenlabs.music.compose_detailed(
    prompt="Berlin night club techno",
    music_length_ms=60000,
    store_for_inpainting=True
)
song_id = response.song_id
```

```typescript
const response = await elevenlabs.music.composeDetailed({
  prompt: "Berlin night club techno",
  musicLengthMs: 60000,
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original (60s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno.mp3" />

### Extend with new intro and outro

```python
extend_plan = {
    "positive_global_styles": [],
    "negative_global_styles": [],
    "sections": [
        {
            "section_name": "New Intro",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 30000,
            "lines": []
        },
        {
            "section_name": "Original Core",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 40000,
            "source_from": {
                "song_id": song_id,
                "range": {"start_ms": 10000, "end_ms": 50000}
            },
            "lines": []
        },
        {
            "section_name": "New Outro",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 30000,
            "lines": []
        }
    ]
}

audio = elevenlabs.music.compose(composition_plan=extend_plan)
```

```typescript
const extendPlan = {
  positiveGlobalStyles: [],
  negativeGlobalStyles: [],
  sections: [
    {
      sectionName: "New Intro",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 30000,
      lines: [],
    },
    {
      sectionName: "Original Core",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 40000,
      sourceFrom: {
        songId,
        range: { startMs: 10000, endMs: 50000 },
      },
      lines: [],
    },
    {
      sectionName: "New Outro",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 30000,
      lines: [],
    },
  ],
};

const audio = await elevenlabs.music.compose({ compositionPlan: extendPlan });
```

<elevenlabs-audio-player audio-title="Extended (100s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno_extended.mp3" />

### Create a seamless loop

Generate a musical phrase and create a loop using a "glue" section.

### Generate a short clip

```python
composition_plan = {
    "positive_global_styles": ["acoustic guitar", "fingerpicking", "warm tone"],
    "negative_global_styles": ["electric", "drums", "electronic"],
    "sections": [
        {
            "section_name": "Solo Acoustic",
            "positive_local_styles": ["fingerpicking", "soft dynamics"],
            "negative_local_styles": [],
            "duration_ms": 10000,
            "lines": []
        }
    ]
}

response = elevenlabs.music.compose_detailed(
    composition_plan=composition_plan,
    store_for_inpainting=True
)
song_id = response.song_id
```

```typescript
const compositionPlan = {
  positiveGlobalStyles: ["acoustic guitar", "fingerpicking", "warm tone"],
  negativeGlobalStyles: ["electric", "drums", "electronic"],
  sections: [
    {
      sectionName: "Solo Acoustic",
      positiveLocalStyles: ["fingerpicking", "soft dynamics"],
      negativeLocalStyles: [],
      durationMs: 10000,
      lines: [],
    },
  ],
};

const response = await elevenlabs.music.composeDetailed({
  compositionPlan,
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original (10s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar.mp3" />

### Create a loop with glue section

```python
loop_plan = {
    "positive_global_styles": [],
    "negative_global_styles": [],
    "sections": [
        {
            "section_name": "Loop Start",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 5000,
            "source_from": {
                "song_id": song_id,
                "range": {"start_ms": 3000, "end_ms": 8000}
            },
            "lines": []
        },
        {
            # Glue section - model generates a smooth transition
            "section_name": "Glue",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 3000,
            "lines": []
        },
        {
            "section_name": "Loop End",
            "positive_local_styles": [],
            "negative_local_styles": [],
            "duration_ms": 5000,
            "source_from": {
                "song_id": song_id,
                "range": {"start_ms": 3000, "end_ms": 8000}
            },
            "lines": []
        }
    ]
}

audio = elevenlabs.music.compose(composition_plan=loop_plan)
```

```typescript
const loopPlan = {
  positiveGlobalStyles: [],
  negativeGlobalStyles: [],
  sections: [
    {
      sectionName: "Loop Start",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 5000,
      sourceFrom: {
        songId,
        range: { startMs: 3000, endMs: 8000 },
      },
      lines: [],
    },
    {
      // Glue section - model generates a smooth transition
      sectionName: "Glue",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 3000,
      lines: [],
    },
    {
      sectionName: "Loop End",
      positiveLocalStyles: [],
      negativeLocalStyles: [],
      durationMs: 5000,
      sourceFrom: {
        songId,
        range: { startMs: 3000, endMs: 8000 },
      },
      lines: [],
    },
  ],
};

const audio = await elevenlabs.music.compose({ compositionPlan: loopPlan });
```

<elevenlabs-audio-player audio-title="Seamless Loop" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar_looped.mp3" />

## Constraints

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

## Next steps

Learn composition plan fundamentals

Complete API documentation