PoradnikiMuzyka

Plany kompozycji

Precyzyjna kontrola nad generowaniem muzyki dzięki ustrukturyzowanemu JSON

Plany kompozycji dają precyzyjną kontrolę nad generowaniem muzyki. Plan music_v2 lub music_v2_5 to uporządkowana lista chunków, z których każdy definiuje sekcję utworu z własnym stylem, tekstem i czasem trwania. Do szybkiego prototypowania używaj promptów tekstowych, a planów kompozycji, gdy potrzebujesz konkretnej struktury chunków, precyzyjnego timing tekstu lub złożonych aranżacji.

Plany kompozycji i prompty tekstowe wzajemnie się wykluczają. Używaj jednego albo drugiego, nie obu.

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

Plany kompozycji oparte na chunkach wymagają music_v2 lub music_v2_5. Podczas komponowania przekaż model_id="music_v2_5".

Szybki start

Wykonaj kroki z krótkiego przewodnika po muzyce, aby skonfigurować klucz API i zainstalować SDK, a potem użyj planów kompozycji, by zyskać większą kontrolę.

1

Generuj muzykę za pomocą planu kompozycji

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

Utwórz plan na podstawie promptu

Utwórz plan kompozycji na podstawie opisu tekstowego, a następnie zmodyfikuj go przed generowaniem:

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

Opis struktury

Chunks

Plan kompozycji to uporządkowana lista do 30 chunków. Każdy chunk generuje jedną sekcję utworu na podstawie text i stylów. Pierwszy chunk jest najważniejszy: jego style określają ogólny ton i gatunek całego utworu.

PoleTypOpis
textstringNazwa sekcji w nawiasach kwadratowych ([Verse 1]), wersy tekstu i instrukcje w nawiasach klamrowych ({scratching}).
duration_msnumberDługość w milisekundach (3 000–120 000).
positive_stylesarrayStyle i instrukcje do uwzględnienia (maks. 50).
negative_stylesarrayStyle i instrukcje, których należy unikać (maks. 50). Domyślnie puste.
context_adherencestringlow, medium lub high (domyślnie). Określa, jak ściśle chunk podąża za sąsiednimi chunkami.

Utwór może mieć do 30 chunków. Łączny czas trwania musi wynosić od 3 sekund do 10 minut, a każdy chunk od 3 do 120 sekund.

Style pierwszego chunku są najważniejsze, bo określają ogólny ton i gatunek. We wczesnych chunkach używaj co najmniej 6–7 stylów, aż ustalisz kierunek. Ogólne style, takie jak “great production quality”, warto domyślnie dodawać do listy.

Chunki mogą też odwoływać się do audio z zapisanego utworu, aby zachować istniejące sekcje bez zmian lub na ich podstawie generować nowe audio. Zobacz uzupełnianie muzyki, aby edytować i łączyć istniejące utwory.

Pisanie tekstów

Pole text łączy nazwę sekcji, tekst i instrukcje w tekście:

  • Nazwa sekcji w nawiasach kwadratowych: [Verse 1], [Chorus], [Bridge]
  • Tekst jako zwykły tekst, z każdą linią oddzieloną przejściem do nowej linii (\n)
  • Dźwięki fonetyczne w nawiasach: (hmmm hmmm), (ooh), (yeah)
  • Instrukcje w tekście w nawiasach klamrowych: {guitar solo}, {scratching}, {instrumental break}

Dla krótkich wskazówek w tekście używaj nawiasów klamrowych. Dla szerszych cech dotyczących całego chunku — gatunku, instrumentacji lub ogólnego stylu wokalu — użyj zamiast tego positive_styles.

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

W poprawionym przykładzie ogólny styl wokalu przeniesiono do positive_styles, a krótka wskazówka w tekście pozostała w text i używa nawiasów klamrowych zamiast zwykłych.

Wskazówki dotyczące stylów

Stosuj konkretne opisy stylów:

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

Swobodnie używaj stylów negatywnych, by uniknąć niechcianych dźwięków. Style muszą być po angielsku (tekst może być w dowolnym języku).

Jeśli uwzględnisz w stylach treści chronione prawem autorskim, API zwróci błąd bad_composition_plan z sugerowaną alternatywą. Zobacz obsługę materiałów chronionych prawem autorskim.

Przykłady

Instrumental kinowy

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

Reklama z nałożonym głosem

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

Kolejne kroki

Szybki start z muzyką

Zacznij od podstaw generowania muzyki

Uzupełnianie muzyki

Remiksuj, wydłużaj i łącz sekcje istniejących utworów

Dokumentacja API

Pełna dokumentacja API

Przewodnik po promptach

Dobre praktyki tworzenia promptów do muzyki