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

# Piani di composizione

I piani di composizione offrono un controllo dettagliato sulla generazione musicale. Un piano `music_v2` o `music_v2_5` è un elenco ordinato di chunk, in cui ogni chunk definisce una sezione del brano con stili, testi e durata propri. Usa prompt di testo per prototipare rapidamente e i piani di composizione quando ti servono una struttura specifica dei chunk, una sincronizzazione precisa dei testi o arrangiamenti complessi.

> **Warning**
>
> I piani di composizione e i prompt di testo si escludono a vicenda. Usa l'uno o l'altro, non entrambi.

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

> **Note**
>
> I piani di composizione basati su chunk richiedono `music_v2` o `music_v2_5`. Passa `model_id="music_v2_5"`
> durante la composizione.

## Guida rapida

Segui la [guida rapida per la musica](/docs/it/eleven-api/guides/cookbooks/music) per configurare la tua chiave API e installare l'SDK, quindi usa i piani di composizione per avere maggiore controllo.

### Genera musica con un piano di composizione

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

### Genera un piano da un prompt

Genera un piano di composizione da una descrizione testuale, quindi modificalo prima di generare:

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

## Riferimento della struttura

### Chunk

Un piano di composizione è un elenco ordinato di massimo 30 chunk. Ogni chunk genera una sezione del brano a partire da `text` e dagli stili. Il primo chunk è il più importante: i suoi stili determinano il tono e il genere complessivi dell'intero brano.

| Campo               | Tipo   | Descrizione                                                                                                                        |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `text`              | string | Nome della sezione tra parentesi quadre (`[Verse 1]`), righe del testo e indicazioni inline tra parentesi graffe (`{scratching}`). |
| `duration_ms`       | number | Durata in millisecondi (3.000 - 120.000).                                                                                          |
| `positive_styles`   | array  | Stili e indicazioni da includere (max 50).                                                                                         |
| `negative_styles`   | array  | Stili e indicazioni da evitare (max 50). Il valore predefinito è vuoto.                                                            |
| `context_adherence` | string | `low`, `medium` o `high` (predefinito). Quanto strettamente il chunk segue quelli circostanti.                                     |

Un brano può avere fino a 30 chunk. La durata totale deve essere compresa tra 3 secondi e 10 minuti, con ogni chunk tra 3 e 120 secondi.

> **Tip**
>
> Gli stili del primo chunk sono i più importanti perché determinano il tono e il genere complessivi. Cerca
> di usare almeno 6-7 stili nei primi chunk finché non è stabilita la direzione. Stili generici come
> "great production quality" sono buoni valori predefiniti da aggiungere all'elenco.

I chunk possono anche fare riferimento all'audio di un brano memorizzato per mantenere invariate le sezioni esistenti o condizionare un nuovo audio su di esse. Consulta [inpainting musicale](/docs/it/eleven-api/guides/how-to/music/inpainting) per modificare e combinare brani esistenti.

## Scrivere i testi

Il campo `text` combina il nome della sezione, il testo e le indicazioni inline:

* **Nome della sezione** tra parentesi quadre: `[Verse 1]`, `[Chorus]`, `[Bridge]`
* **Testo** come testo normale, con ogni riga separata da un'interruzione di riga (`\n`)
* **Suoni fonetici** tra parentesi: `(hmmm hmmm)`, `(ooh)`, `(yeah)`
* **Indicazioni inline** tra parentesi graffe: `{guitar solo}`, `{scratching}`, `{instrumental break}`

Usa le parentesi graffe per segnali brevi e inline. Per caratteristiche più ampie che si applicano all'intero chunk — genere, strumentazione o stile vocale generale — usa invece `positive_styles`.

**`Non corretto`**

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

**`Corretto`**

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

Nell'esempio corretto, lo stile vocale generale viene spostato in `positive_styles`, mentre il breve segnale inline resta in `text` usando le parentesi graffe anziché quelle tonde.

## Suggerimenti sugli stili

Sii specifico con i descrittori di stile:

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

Usa liberamente gli stili negativi per evitare suoni indesiderati. Gli stili devono essere in inglese (i testi possono essere in qualsiasi lingua).

Se includi contenuti protetti da copyright negli stili, l'API restituisce un errore `bad_composition_plan` con un'alternativa suggerita. Consulta [gestione del materiale protetto da copyright](/docs/it/eleven-api/guides/cookbooks/music#copyrighted-material).

## Esempi

### Strumentale cinematografico

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

### Pubblicità con voce fuori campo

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

## Passaggi successivi

#### [Guida rapida per la musica](/docs/it/eleven-api/guides/cookbooks/music)

Inizia con la generazione musicale di base

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

Remix, estendi e unisci sezioni di brani esistenti

#### [Riferimento API](/docs/it/api-reference/music/compose)

Documentazione API completa

#### [Guida ai prompt](/docs/it/overview/capabilities/music/best-practices)

Best practice per i prompt musicali