> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Genre

> List, apply, and import genre libraries and presets. The import step (genre import-songsketch) is CLI-only by design — a hidden, internal command not exposed to end users. It is a content-authoring step that converts a proprietary Song Sketch lib JSON into a .vibraigenre file on disk (how the shipped genre catalog is minted), not a runtime operation an agent drives against Live. The MCP surface (GenreTools) exposes the runtime half: discover libraries and presets (list_genres, list_genre_presets) and apply them (apply_genre). Extraction (genre extract CLI ↔ extract_genre MCP) reverse-derives a genre from the open Live set.

List, apply, and import genre libraries and presets. The import step (genre import-songsketch) is CLI-only by design — a hidden, internal command not exposed to end users. It is a content-authoring step that converts a proprietary Song Sketch lib JSON into a .vibraigenre file on disk (how the shipped genre catalog is minted), not a runtime operation an agent drives against Live. The MCP surface (GenreTools) exposes the runtime half: discover libraries and presets (list\_genres, list\_genre\_presets) and apply them (apply\_genre). Extraction (genre extract CLI ↔ extract\_genre MCP) reverse-derives a genre from the open Live set.

## Command line

### `genre list`

List installed genre libraries

```bash theme={null}
vibrai genre list
```

### `genre presets`

List presets in a genre library

```bash theme={null}
vibrai genre presets <genre>
```

<ParamField path="genre" required>
  Genre id or display name (run 'vibrai genre list')
</ParamField>

### `genre import-songsketch`

Convert a Song Sketch lib JSON file to a .vibraigenre

```bash theme={null}
vibrai genre import-songsketch <json> --out <DIR>
```

<ParamField path="json" required>
  Path to a Song Sketch lib JSON file
</ParamField>

<ParamField path="--out">
  Output directory (defaults to \~/.vibrai/genres)
</ParamField>

### `genre apply`

Apply a genre+preset to a .vibrai project

```bash theme={null}
vibrai genre apply [genre] [preset] [project-path] --genre <NAME> --preset <ID> --yes
```

<ParamField path="genre">
  Genre id or display name (run 'vibrai genre list').
</ParamField>

<ParamField path="preset">
  Preset id or display name within the genre (from 'vibrai genre presets \<genre>').
</ParamField>

<ParamField path="project-path">
  Path to .vibrai (default: ./project.vibrai)
</ParamField>

<ParamField path="--genre">
  (deprecated) Use positional \<genre> instead. Will be removed in the next minor release.
</ParamField>

<ParamField path="--preset">
  (deprecated) Use positional \<preset> instead. Will be removed in the next minor release.
</ParamField>

<ParamField path="--yes">
  Confirm destructive overwrite of sections / parts / templates / arrangement / generation
</ParamField>

### `genre extract`

Extract a genre from the open Live set into a .vibraigenre

```bash theme={null}
vibrai genre extract --name <DISPLAY> --out <DIR> --into <GENRE> --preset-name <N> --faithful --source <MODE> --part <OVERRIDE> --force
```

<ParamField path="--name">
  Genre display name; the filename slug derives from it. Defaults to the open Live set's name.
</ParamField>

<ParamField path="--out">
  Output directory (defaults to \~/.vibrai/genres so the genre is immediately applicable)
</ParamField>

<ParamField path="--into">
  Append the set as a new preset to this existing user genre instead of creating a file
</ParamField>

<ParamField path="--preset-name">
  Name of the preset this set becomes (defaults to the set name)
</ParamField>

<ParamField path="--faithful">
  Also embed literal note phrases (writes format v3 with playback support)
</ParamField>

<ParamField path="--source" default="auto">
  auto|arrangement|session — auto uses the arrangement when it has clips, else the session
</ParamField>

<ParamField path="--part">
  Classification override as \<trackId>:\<PartType>, repeatable (track ids as shown in the report)
</ParamField>

<ParamField path="--force">
  Overwrite an existing target .vibraigenre
</ParamField>

## MCP tools

### `list_genres`

List installed genre libraries. Returns each genre's name (slug; other tools accept either the slug or the display name), display name, sub-genres, default BPM, and preset count. Embedded resources ship with Vibrai; users can override or add entries via \~/.vibrai/genres/\<name>.vibraigenre.

```json theme={null}
{
  "tool": "list_genres",
  "arguments": {}
}
```

### `list_genre_presets`

List presets in a genre library. Each entry has id (use with apply\_genre / init\_project --preset), display name, sub-genre, section/part counts, and an instrumentation summary (snake\_case PartType -> stock instrument path, resolved for the preset's own sub-genre) from the genre's defaults table — omitted when the genre has none.

```json theme={null}
{
  "tool": "list_genre_presets",
  "arguments": {
    "genre": "<String>"
  }
}
```

<ParamField path="genre" type="String" required>
  Genre id (slug from list\_genres) or display name.
</ParamField>

### `apply_genre`

Materialize a genre+preset into a .vibrai project at the given path. Destructive: overwrites sections, parts, templates, arrangement.blueprint, and generation — requires confirm=true (parity with the CLI's `genre apply --yes`); refuses without modifying the project otherwise. Preserves meta.name and meta.als\_path from the existing project if present. Note: the `preset_id` parameter was renamed to `preset` for CLI/MCP naming parity; update any callers.

```json theme={null}
{
  "tool": "apply_genre",
  "arguments": {
    "genre": "<String>",
    "preset": "<String>",
    "project_path": "<String>",
    "confirm": "<Boolean>"
  }
}
```

<ParamField path="genre" type="String" required>
  Genre id (slug from list\_genres) or display name.
</ParamField>

<ParamField path="preset" type="String" required>
  Preset id or display name within the genre (from list\_genre\_presets).
</ParamField>

<ParamField path="project_path" type="String" required>
  Absolute path to the .vibrai project file.
</ParamField>

<ParamField path="confirm" type="Boolean">
  Confirm the destructive overwrite (CLI --yes equivalent). Must be true to proceed; confirm with the user first when the project already has content.
</ParamField>

### `extract_genre`

Extract a genre from the open Live set into a .vibraigenre file. Reads tempo, scale, tracks, clips, notes, and envelopes; classifies tracks into parts (report shows each decision); detects sections; and writes a generative genre usable by apply\_genre. Set faithful=true to also embed literal note phrases (format v3) so regeneration seeds from the source riffs. Set into\_genre=\<user genre> to append this set as a new preset instead of creating a file. Re-run with part\_overrides to correct classifications — extraction never mutates the Live set.

```json theme={null}
{
  "tool": "extract_genre",
  "arguments": {
    "name": "<String>",
    "out_dir": "<String>",
    "into_genre": "<String>",
    "preset_name": "<String>",
    "faithful": "<Boolean>",
    "source": "<String>",
    "part_overrides": "<Dictionary<String, String>>",
    "force": "<Boolean>"
  }
}
```

<ParamField path="name" type="String">
  Genre display name; filename slug derives from it. Defaults to the open set's name.
</ParamField>

<ParamField path="out_dir" type="String">
  Output directory. Defaults to \~/.vibrai/genres so the genre is immediately applicable.
</ParamField>

<ParamField path="into_genre" type="String">
  Append as a new preset to this existing user genre instead of creating a new file.
</ParamField>

<ParamField path="preset_name" type="String">
  Name of the preset this set becomes. Defaults to the set name.
</ParamField>

<ParamField path="faithful" type="Boolean">
  Also embed literal note phrases (writes format v3 with playback support).
</ParamField>

<ParamField path="source" type="String">
  auto|arrangement|session — auto uses the arrangement when it has clips, else the session.
</ParamField>

<ParamField path="part_overrides" type="Dictionary<String, String>">
  Classification overrides: track id (as shown in the report) → PartType, e.g. \{"3": "hi\_hat"}.
</ParamField>

<ParamField path="force" type="Boolean">
  Overwrite an existing target file.
</ParamField>