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

# Plans de composition

Les plans de composition offrent un contrôle précis de la génération musicale. Un plan `music_v2` ou `music_v2_5` est une liste ordonnée de segments, chaque segment définissant une section du morceau avec ses propres styles, paroles et durée. Utilisez des prompts textuels pour le prototypage rapide et des plans de composition lorsque vous avez besoin d’une structure de segments spécifique, d’un minutage précis des paroles ou d’arrangements complexes.

> **Warning**
>
> Les plans de composition et les prompts textuels s’excluent mutuellement. Utilisez l’un ou l’autre, pas les deux.

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

> **Note**
>
> Les plans de composition basés sur des segments nécessitent `music_v2` ou `music_v2_5`. Transmettez `model_id="music_v2_5"`
> lors de la composition.

## Démarrage rapide

Suivez le [guide de démarrage rapide de la musique](/docs/fr/eleven-api/guides/cookbooks/music) pour configurer votre clé API et installer le SDK, puis utilisez les plans de composition pour bénéficier de davantage de contrôle.

### Générer de la musique avec un plan de composition

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

### Générer un plan à partir d’un prompt

Générez un plan de composition à partir d’une description textuelle, puis modifiez-le avant la génération :

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

## Référence de structure

### Segments

Un plan de composition est une liste ordonnée de 30 segments maximum. Chaque segment génère une section du morceau à partir de son `text` et de ses styles. Le premier segment est le plus important : ses styles définissent le ton et le genre généraux de tout le morceau.

| Champ               | Type    | Description                                                                                                               |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `text`              | chaîne  | Nom de section entre crochets (`[Verse 1]`), lignes de paroles et indications intégrées entre accolades (`{scratching}`). |
| `duration_ms`       | nombre  | Durée en millisecondes (3 000 - 120 000).                                                                                 |
| `positive_styles`   | tableau | Styles et indications à inclure (50 maximum).                                                                             |
| `negative_styles`   | tableau | Styles et indications à éviter (50 maximum). Vide par défaut.                                                             |
| `context_adherence` | chaîne  | `low`, `medium` ou `high` (par défaut). Indique à quel point le segment suit les segments environnants.                   |

Un morceau peut comporter jusqu’à 30 segments. Sa durée totale doit être comprise entre 3 secondes et 10 minutes, chaque segment durant entre 3 et 120 secondes.

> **Tip**
>
> Les styles du premier segment sont les plus importants, car ils définissent le ton et le genre généraux. Visez
> au moins 6 à 7 styles dans les premiers segments, jusqu’à ce que la direction soit établie. Des styles génériques tels que
> « great production quality » sont de bons paramètres par défaut à ajouter à la liste.

Les segments peuvent également référencer l’audio d’un morceau stocké pour conserver des sections existantes inchangées ou conditionner de nouveaux fichiers audio à partir de celles-ci. Consultez [l’inpainting musical](/docs/fr/eleven-api/guides/how-to/music/inpainting) pour modifier et combiner des morceaux existants.

## Écrire des paroles

Le champ `text` combine le nom de la section, les paroles et les indications intégrées :

* **Nom de section** entre crochets : `[Verse 1]`, `[Chorus]`, `[Bridge]`
* **Paroles** en texte brut, chaque ligne étant séparée par un saut de ligne (`\n`)
* **Sons phonétiques** entre parenthèses : `(hmmm hmmm)`, `(ooh)`, `(yeah)`
* **Indications intégrées** entre accolades : `{guitar solo}`, `{scratching}`, `{instrumental break}`

Utilisez les accolades pour des indications intégrées courtes. Pour des caractéristiques plus générales qui s’appliquent à l’ensemble du segment, comme le genre, l’instrumentation ou le style vocal global, utilisez plutôt `positive_styles`.

**`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"]
}
```

Dans l’exemple corrigé, le style vocal global passe dans `positive_styles`, tandis que l’indication intégrée courte reste dans `text`, entre accolades plutôt qu’entre parenthèses.

## Conseils de style

Soyez précis dans vos descripteurs de style :

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

Utilisez largement les styles négatifs pour éviter les sons indésirables. Les styles doivent être en anglais, mais les paroles peuvent être dans n’importe quelle langue.

Si vous incluez du contenu protégé par des droits d’auteur dans les styles, l’API renvoie une erreur `bad_composition_plan` avec une alternative suggérée. Consultez [la gestion des contenus protégés par des droits d’auteur](/docs/fr/eleven-api/guides/cookbooks/music#copyrighted-material).

## Exemples

### Instrumental cinématographique

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

### Publicité avec voix off

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

## Étapes suivantes

#### [Démarrage rapide de la musique](/docs/fr/eleven-api/guides/cookbooks/music)

Lancez-vous avec la génération musicale de base

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

Remixez, prolongez et assemblez des sections de morceaux existants

#### [Guide de l’API](/docs/fr/api-reference/music/compose)

Documentation complète de l’API

#### [Guide de prompting](/docs/fr/overview/capabilities/music/best-practices)

Bonnes pratiques pour les prompts musicaux