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

# Compositieplannen

Compositieplannen bieden gedetailleerde controle over muziekgeneratie. Een `music_v2`- of `music_v2_5`-plan is een geordende lijst met chunks, waarbij elke chunk een sectie van het nummer definieert met eigen stijlen, songtekst en duur. Gebruik tekstprompts voor snelle prototyping en compositieplannen wanneer je een specifieke chunkstructuur, nauwkeurige timing van songteksten of complexe arrangementen nodig hebt.

> **Warning**
>
> Compositieplannen en tekstprompts sluiten elkaar uit. Gebruik het een of het ander, niet beide.

```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**
>
> Compositieplannen op basis van chunks vereisen `music_v2` of `music_v2_5`. Geef bij het componeren `model_id="music_v2_5"`
> door.

## Quickstart

Volg de [quickstart voor muziek](/docs/nl/eleven-api/guides/cookbooks/music) om je API-sleutel in te stellen en de SDK te installeren, en gebruik vervolgens compositieplannen voor meer controle.

### Muziek genereren met een compositieplan

```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
});
```

### Een plan genereren vanuit een prompt

Genereer een compositieplan op basis van een tekstbeschrijving en pas het aan voordat je genereert:

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

## Structuurreferentie

### Chunks

Een compositieplan is een geordende lijst met maximaal 30 chunks. Elke chunk genereert één sectie van het nummer vanuit de bijbehorende `text` en stijlen. De eerste chunk is het belangrijkst: de stijlen bepalen de algemene sfeer en het genre voor het hele nummer.

| Veld                | Type   | Beschrijving                                                                                                                   |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `text`              | string | Sectienaam tussen vierkante haken (`[Verse 1]`), regels met songtekst en inline-instructies tussen accolades (`{scratching}`). |
| `duration_ms`       | number | Lengte in milliseconden (3.000 - 120.000).                                                                                     |
| `positive_styles`   | array  | Stijlen en instructies om op te nemen (max. 50).                                                                               |
| `negative_styles`   | array  | Stijlen en instructies om te vermijden (max. 50). Standaard leeg.                                                              |
| `context_adherence` | string | `low`, `medium` of `high` (standaard). Hoe nauw de chunk de omringende chunks volgt.                                           |

Een nummer kan maximaal 30 chunks hebben. De totale duur moet tussen 3 seconden en 10 minuten liggen, met elke chunk tussen 3 en 120 seconden.

> **Tip**
>
> De stijlen voor de eerste chunk zijn het belangrijkst, omdat ze de algemene sfeer en het genre bepalen. Streef
> naar minstens 6-7 stijlen in vroege chunks totdat de richting is vastgesteld. Algemene stijlen zoals
> "great production quality" zijn goede standaardwaarden om aan de lijst toe te voegen.

Chunks kunnen ook verwijzen naar audio van een opgeslagen nummer om bestaande secties ongewijzigd te houden of nieuwe audio daarop te baseren. Zie [muziek-inpainting](/docs/nl/eleven-api/guides/how-to/music/inpainting) voor het bewerken en combineren van bestaande nummers.

## Songteksten schrijven

Het veld `text` combineert de sectienaam, songtekst en inline-instructies:

* **Sectienaam** tussen vierkante haken: `[Verse 1]`, `[Chorus]`, `[Bridge]`
* **Songtekst** als platte tekst, met elke regel gescheiden door een regeleinde (`\n`)
* **Fonetische klanken** tussen haakjes: `(hmmm hmmm)`, `(ooh)`, `(yeah)`
* **Inline-instructies** tussen accolades: `{guitar solo}`, `{scratching}`, `{instrumental break}`

Gebruik accolades voor korte, inline aanwijzingen. Gebruik voor bredere kenmerken die gelden voor de hele chunk — genre, instrumentatie of algemene zangstijl — in plaats daarvan `positive_styles`.

**`Onjuist`**

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

**`Juist`**

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

In het gecorrigeerde voorbeeld wordt de algemene zangstijl verplaatst naar `positive_styles`, terwijl de korte inline-aanwijzing in `text` blijft met accolades in plaats van haakjes.

## Stijltips

Wees specifiek met stijlbeschrijvingen:

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

Gebruik negatieve stijlen ruimhartig om ongewenste geluiden te voorkomen. Stijlen moeten in het Engels zijn (songteksten mogen in elke taal zijn).

Als je auteursrechtelijk beschermde content in stijlen opneemt, retourneert de API een fout `bad_composition_plan` met een voorgesteld alternatief. Zie [omgaan met auteursrechtelijk beschermd materiaal](/docs/nl/eleven-api/guides/cookbooks/music#copyrighted-material).

## Voorbeelden

### Cinematisch instrumentaal

```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="Cinematic Instrumental" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-cinematic-instrumental.mp3" />

### Advertentie met voice-over

```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="Advertisement" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-advertisement.mp3" />

## Volgende stappen

#### [Quickstart voor muziek](/docs/nl/eleven-api/guides/cookbooks/music)

Ga aan de slag met eenvoudige muziekgeneratie

#### [Muziek-inpainting](/docs/nl/eleven-api/guides/how-to/music/inpainting)

Remix, verleng en voeg secties van bestaande nummers samen

#### [API-referentie](/docs/nl/api-reference/music/compose)

Volledige API-documentatie

#### [Promptinggids](/docs/nl/overview/capabilities/music/best-practices)

Best practices voor muziekprompts