AnleitungenMusik

Kompositionspläne

Präzise Steuerung der Musikgenerierung mit strukturiertem JSON

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.

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

{
  "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"
    }
  ]
}

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, um Ihren API-Schlüssel einzurichten und das SDK zu installieren. Nutzen Sie anschließend Kompositionspläne für mehr Kontrolle.

1

Musik mit einem Kompositionsplan generieren

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)
2

Einen Plan aus einem Prompt generieren

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

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

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.

FeldTypBeschreibung
textstringAbschnittsname in eckigen Klammern ([Verse 1]), Liedtextzeilen und Inline-Anweisungen in geschweiften Klammern ({scratching}).
duration_msnumberLänge in Millisekunden (3.000–120.000).
positive_stylesarrayEinzuschließende Stile und Anweisungen (max. 50).
negative_stylesarrayZu vermeidende Stile und Anweisungen (max. 50). Standardmäßig leer.
context_adherencestringlow, 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.

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.

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.

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

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:

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

Beispiele

Filmisches Instrumentalstück

{
  "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"
    }
  ]
}

Werbung mit Voiceover

{
  "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"
    }
  ]
}

Nächste Schritte

Musik-Schnellstart

Einstieg in die grundlegende Musikgenerierung

Musik-Inpainting

Abschnitte bestehender Songs remixen, erweitern und zusammenfügen

API-Referenz

Vollständige API-Dokumentation

Prompting-Leitfaden

Best Practices für Musik-Prompts