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

# Kompositionspläne

Kompositionspläne ermöglichen eine präzise Steuerung der Musikgenerierung. Ein `music_v2`- oder `music_v2_5`-Plan ist eine geordnete Liste von Chunks, wobei jeder Chunk einen Songabschnitt mit eigenen Stilen, Liedtexten und einer eigenen Dauer definiert. Nutzen Sie Text-Prompts für schnelles Prototyping und Kompositionspläne, wenn Sie eine bestimmte Chunk-Struktur, präzises Timing der Liedtexte oder komplexe Arrangements benötigen.

> **Warning**
>
> Kompositionspläne und Text-Prompts schließen sich gegenseitig aus. Verwenden Sie entweder das eine oder das andere, nicht beides.

```json
{
  "chunks": [
    {
      "text": "[Verse 1]\nWoke up today with a feeling inside\nSomething is changing I cannot hide\nThe sun on my face and the wind at my back\nI'm finally ready to get on track",
      "duration_ms": 16000,
      "positive_styles": [
        "upbeat pop",
        "female vocalist with clear tone",
        "acoustic guitar and light synths",
        "gentle and conversational vocals",
        "light drums in background",
        "polished production",
        "120 BPM",
        "C major"
      ],
      "negative_styles": ["dark", "aggressive", "slow tempo", "a cappella"],
      "context_adherence": "high"
    },
    {
      "text": "[Verse 2]\nUsed to be scared of the world outside\nBuilding up walls where I used to hide\nBut now I see clearly what I need to do\nTake that first step into something new",
      "duration_ms": 16000,
      "positive_styles": [
        "confident vocals",
        "fuller guitar strumming",
        "steady drum beat",
        "bass joins in"
      ],
      "negative_styles": ["a cappella", "sparse", "quiet"],
      "context_adherence": "high"
    },
    {
      "text": "[Pre-Chorus]\nNo more waiting for tomorrow\nThis is my time now",
      "duration_ms": 8000,
      "positive_styles": [
        "building intensity",
        "rising synth melody",
        "driving drums",
        "full band playing"
      ],
      "negative_styles": ["a cappella", "dropping out"],
      "context_adherence": "high"
    },
    {
      "text": "[Chorus]\nI'm breaking through\nNothing's gonna stop me now\nI'm breaking through\nFinally found out how",
      "duration_ms": 16000,
      "positive_styles": [
        "powerful and anthemic vocals",
        "full band at maximum energy",
        "punchy drums and bass",
        "layered synths and guitar"
      ],
      "negative_styles": ["a cappella", "minimal", "stripped back"],
      "context_adherence": "high"
    },
    {
      "text": "[Outro]",
      "duration_ms": 8000,
      "positive_styles": [
        "instrumental fade out",
        "guitar melody repeating",
        "drums softening",
        "gentle ending"
      ],
      "negative_styles": ["vocals", "abrupt ending", "building"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Pop Song" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-pop-song.mp3" />

> **Note**
>
> Chunk-basierte Kompositionspläne erfordern `music_v2` oder `music_v2_5`. Übergeben Sie beim Komponieren `model_id="music_v2_5"`.

## Schnellstart

Folgen Sie dem [Musik-Schnellstart](/docs/de/eleven-api/guides/cookbooks/music), um Ihren API-Schlüssel einzurichten und das SDK zu installieren. Nutzen Sie anschließend Kompositionspläne für mehr Kontrolle.

### Musik mit einem Kompositionsplan generieren

```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 = {
    "chunks": [
        {
            "text": "[Verse]\nWalking down an empty street\nWondering who I'll meet",
            "duration_ms": 15000,
            "positive_styles": ["pop", "upbeat", "female vocals", "soft vocals", "acoustic guitar"],
            "negative_styles": ["dark", "slow"],
            "context_adherence": "high"
        },
        {
            "text": "[Chorus]\nThis is my moment\nI won't let it go",
            "duration_ms": 15000,
            "positive_styles": ["powerful vocals", "full band"],
            "negative_styles": [],
            "context_adherence": "high"
        }
    ]
}

audio = elevenlabs.music.compose(
    composition_plan=composition_plan,
    model_id="music_v2_5",
    # 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 = {
  chunks: [
    {
      text: "[Verse]\nWalking down an empty street\nWondering who I'll meet",
      durationMs: 15000,
      positiveStyles: ["pop", "upbeat", "female vocals", "soft vocals", "acoustic guitar"],
      negativeStyles: ["dark", "slow"],
      contextAdherence: "high",
    },
    {
      text: "[Chorus]\nThis is my moment\nI won't let it go",
      durationMs: 15000,
      positiveStyles: ["powerful vocals", "full band"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await elevenlabs.music.compose({
  compositionPlan,
  modelId: "music_v2_5",
  // withTimestamps: true,  // Optional: return word-level timestamps
});
```

### Einen Plan aus einem Prompt generieren

Generieren Sie einen Kompositionsplan aus einer Textbeschreibung und passen Sie ihn vor der Generierung an:

```python
plan = elevenlabs.music.composition_plan.create(
    prompt="An upbeat pop song about summer adventures",
    music_length_ms=60000,
    model_id="music_v2_5"
)

# Modify the generated plan
plan["chunks"][0]["text"] = "[Verse 1]\nCustom lyrics here"

audio = elevenlabs.music.compose(composition_plan=plan, model_id="music_v2_5")
```

```typescript
const plan = await elevenlabs.music.compositionPlan.create({
  prompt: "An upbeat pop song about summer adventures",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

// Modify the generated plan
plan.chunks[0].text = "[Verse 1]\nCustom lyrics here";

const audio = await elevenlabs.music.compose({ compositionPlan: plan, modelId: "music_v2_5" });
```

## Strukturreferenz

### Chunks

Ein Kompositionsplan ist eine geordnete Liste von bis zu 30 Chunks. Jeder Chunk generiert anhand seines `text` und seiner Stile einen Songabschnitt. Der erste Chunk ist am wichtigsten: Seine Stile legen Ton und Genre für den gesamten Song fest.

| Feld                | Typ    | Beschreibung                                                                                                                       |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `text`              | string | Abschnittsname in eckigen Klammern (`[Verse 1]`), Liedtextzeilen und Inline-Anweisungen in geschweiften Klammern (`{scratching}`). |
| `duration_ms`       | number | Länge in Millisekunden (3.000–120.000).                                                                                            |
| `positive_styles`   | array  | Einzuschließende Stile und Anweisungen (max. 50).                                                                                  |
| `negative_styles`   | array  | Zu vermeidende Stile und Anweisungen (max. 50). Standardmäßig leer.                                                                |
| `context_adherence` | string | `low`, `medium` oder `high` (Standard). Wie eng der Chunk seinen umgebenden Chunks folgt.                                          |

Ein Song kann bis zu 30 Chunks enthalten. Die Gesamtdauer muss zwischen 3 Sekunden und 10 Minuten liegen; jeder Chunk muss zwischen 3 und 120 Sekunden lang sein.

> **Tip**
>
> Die Stile des ersten Chunks sind am wichtigsten, da sie Ton und Genre insgesamt festlegen. Verwenden Sie in frühen Chunks mindestens 6–7 Stile, bis die Richtung feststeht. Allgemeine Stile wie
> "great production quality" eignen sich gut als Standardergänzung für die Liste.

Chunks können auch auf Audio aus einem gespeicherten Song verweisen, um bestehende Abschnitte unverändert zu lassen oder neues Audio darauf zu konditionieren. Weitere Informationen zum Bearbeiten und Kombinieren bestehender Songs finden Sie unter [Musik-Inpainting](/docs/de/eleven-api/guides/how-to/music/inpainting).

## Liedtexte schreiben

Das Feld `text` kombiniert Abschnittsname, Liedtext und Inline-Anweisungen:

* **Abschnittsname** in eckigen Klammern: `[Verse 1]`, `[Chorus]`, `[Bridge]`
* **Liedtexte** als Klartext, wobei jede Zeile durch einen Zeilenumbruch (`\n`) getrennt ist
* **Phonetische Laute** in Klammern: `(hmmm hmmm)`, `(ooh)`, `(yeah)`
* **Inline-Anweisungen** in geschweiften Klammern: `{guitar solo}`, `{scratching}`, `{instrumental break}`

Verwenden Sie geschweifte Klammern für kurze Inline-Hinweise. Verwenden Sie stattdessen `positive_styles` für übergreifende Merkmale, die für den gesamten Chunk gelten – Genre, Instrumentierung oder allgemeiner Gesangsstil.

**`Incorrect`**

```json title="Incorrect"
{
  "text": "[Verse]\n(soft female vocals) I've been waiting\n(instrumental break)\nfor you"
}
```

**`Correct`**

```json title="Correct"
{
  "text": "[Verse]\nI've been waiting\n{instrumental break}\nfor you",
  "positive_styles": ["soft female vocals"]
}
```

Im korrigierten Beispiel wird der allgemeine Gesangsstil in `positive_styles` verschoben, während der kurze Inline-Hinweis mithilfe geschweifter Klammern statt Klammern in `text` bleibt.

## Stiltipps

Seien Sie bei Stilbeschreibungen konkret:

```json
{
  "positive_styles": [
    "warm acoustic guitar with light fingerpicking",
    "soft female vocals with intimate delivery",
    "gentle percussion with brushed snare",
    "80 BPM"
  ]
}
```

Nutzen Sie negative Stile großzügig, um unerwünschte Klänge zu verhindern. Stile müssen auf Englisch sein; Liedtexte können in jeder Sprache verfasst sein.

Wenn Sie urheberrechtlich geschützte Inhalte in Stilen verwenden, gibt die API einen Fehler `bad_composition_plan` mit einer vorgeschlagenen Alternative zurück. Siehe [Umgang mit urheberrechtlich geschütztem Material](/docs/de/eleven-api/guides/cookbooks/music#copyrighted-material).

## Beispiele

### Filmisches Instrumentalstück

```json
{
  "chunks": [
    {
      "text": "[Tension Build]",
      "duration_ms": 15000,
      "positive_styles": [
        "cinematic",
        "orchestral",
        "epic",
        "low strings tremolo",
        "building intensity",
        "80 BPM",
        "D minor"
      ],
      "negative_styles": ["vocals", "lyrics", "pop", "electronic", "bright"],
      "context_adherence": "high"
    },
    {
      "text": "[Climax]",
      "duration_ms": 15000,
      "positive_styles": ["full orchestra", "brass fanfare", "triumphant"],
      "negative_styles": ["quiet", "vocals"],
      "context_adherence": "high"
    },
    {
      "text": "[Resolution]",
      "duration_ms": 10000,
      "positive_styles": ["gentle strings", "piano melody", "fading out"],
      "negative_styles": ["intense", "vocals"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Filmisches Instrumentalstück" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-cinematic-instrumental.mp3" />

### Werbung mit Voiceover

```json
{
  "chunks": [
    {
      "text": "[Intro]",
      "duration_ms": 5000,
      "positive_styles": [
        "upbeat",
        "modern pop",
        "energetic",
        "120 BPM",
        "instrumental",
        "catchy hook"
      ],
      "negative_styles": ["sad", "slow", "dark", "vocals"],
      "context_adherence": "high"
    },
    {
      "text": "[Voiceover]\nIntroducing the future of productivity\nWork smarter, not harder",
      "duration_ms": 10000,
      "positive_styles": ["spoken voiceover", "confident male voice", "background music"],
      "negative_styles": ["singing"],
      "context_adherence": "high"
    },
    {
      "text": "[Outro]",
      "duration_ms": 5000,
      "positive_styles": ["musical sting", "memorable"],
      "negative_styles": ["vocals"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Werbung" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-advertisement.mp3" />

## Nächste Schritte

#### [Musik-Schnellstart](/docs/de/eleven-api/guides/cookbooks/music)

Einstieg in die grundlegende Musikgenerierung

#### [Musik-Inpainting](/docs/de/eleven-api/guides/how-to/music/inpainting)

Abschnitte bestehender Songs remixen, erweitern und zusammenfügen

#### [API-Referenz](/docs/de/api-reference/music/compose)

Vollständige API-Dokumentation

#### [Prompting-Leitfaden](/docs/de/overview/capabilities/music/best-practices)

Best Practices für Musik-Prompts