fabricatio-yue

AI-powered lyrics composition for music generation with YuE. Provides genre selection, structured lyric generation, and batch song composition integrated into the Fabricatio agent framework.

Installation

pip install fabricatio[yue]

Or with the CLI extras:

pip install fabricatio[yue,cli]

Overview

fabricatio-yue generates complete song lyrics with genre-appropriate structure (verse, chorus, bridge, etc.). It selects suitable genres from a taxonomy of 200+ tags across five categories — genre, instrument, mood, gender, timbre — and feeds them into LLM-driven lyric generation. Songs are saved as Markdown files with embedded metadata.

Key Components

Models

Capabilities

Actions

CLI

yuek compose -r "an upbeat pop song about summer" -o ./output

Usage

from fabricatio_core import Event, Role, Task, WorkFlow
from fabricatio_yue.actions.compose import Compose

ns = "compose"
Role.with_bio(name="composer").subscribe(
    Event.quick_instantiate(ns),
    WorkFlow(steps=(Compose().to_task_output(),))
).dispatch()

Task(name="compose song").update_init_context(
    req="a melancholic jazz ballad",
    output="./songs",
).delegate_blocking(ns)

Using the Lyricize capability directly:

from fabricatio_yue.capabilities.lyricize import Lyricize

lyricizer = Lyricize()
song = await lyricizer.lyricize("a fast punk anthem about resilience")
print(song.model_dump_json(indent=2))

Using SelectGenre:

from fabricatio_yue.capabilities.genre import SelectGenre

selector = SelectGenre()
genres = await selector.gather_genres("dark atmospheric electronic")

Song and Segment model usage:

from fabricatio_yue.models.segment import Segment, Song

segments = [
    Segment(section_type="verse", duration=30, lyrics=["First verse line 1", "First verse line 2"]),
    Segment(section_type="chorus", duration=20, lyrics=["Chorus line 1", "Chorus line 2"]),
]

song = Song(
    name="my_song",
    description="A generated song",
    genres=["electronic", "ambient"],
    segments=segments,
)

song.save_to("./songs")
print(song.duration)  # 50

Dependencies

• fabricatio-core — core agent framework
• more-itertools — flatten genre results
• orjson — fast JSON loading of genre tags
• pydantic — data model validation

Optional CLI extras: questionary, typer.

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.yue] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.yue] in pyproject.toml, or via FABRICATIO_EXT__YUE__<FIELD_UPPER> environment variables.

[ext.yue]

Access at runtime: from fabricatio_yue.config import yue_config.

License

MIT — see LICENSE