# How the OpenMontage Music Library Drop Path Integrates with the Asset Director

> Learn how the OpenMontage music_library drop path integrates with the asset director, making your royalty-free music source intelligent and user-friendly.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The OpenMontage `music_library` tool turns the `music_library/` drop folder into a first-class royalty-free music source that asset directors query during both proposal and asset stages, automatically prioritizing user-provided tracks over API-based generators.**

The OpenMontage framework streamlines video production pipelines by converting a simple local directory into a managed audio asset repository. By leveraging the **music library drop path**, creators can populate a `music_library/` folder at the project root with MP3, WAV, or FLAC files, making them immediately discoverable by asset directors across all pipeline types—including *talking-head*, *cinematic*, and *explainer* workflows. This integration ensures royalty-free tracks surface early in the proposal phase and embed seamlessly into the final asset manifest.

## How the MusicLibrary Tool Discovers Tracks

### Folder Detection and Configuration

The `MusicLibrary` class in [`tools/audio/music_library.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/audio/music_library.py) implements a hierarchical path resolution strategy via the internal `_library_dir()` method. This resolver checks three sources in strict priority order:

1. An explicit `library_dir` parameter passed during tool instantiation
2. The `MUSIC_LIBRARY_DIR` environment variable
3. The default `<project-root>/music_library` directory

This design ensures flexibility for local development and containerized deployments while maintaining a sensible default that requires zero configuration.

### Track Discovery and Metadata Extraction

Once the directory resolves, the `_list_tracks()` method recursively scans the folder for files matching the `_AUDIO_EXTENSIONS` whitelist (which includes MP3, WAV, FLAC, and other standard formats). The discovered tracks are alphabetically sorted to ensure deterministic ordering.

If `ffprobe` is available on the system, the optional `_probe_duration()` method queries each track's length. The aggregated metadata—including file name, absolute path, size, and duration—populates the tool's output schema, providing asset directors with complete track specifications for selection interfaces.

## Tool Registration and Capability Exposure

The `MusicLibrary` tool registers itself automatically through the **tool registry** ([`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py)) via the `registry.discover()` mechanism. It exposes the capability string `music_library` and includes `install_instructions` that document the drop-folder contract for users.

Asset directors access this capability declaratively rather than instantiating the class directly:

```python
from tools.tool_registry import registry

# Retrieve the MusicLibrary tool by capability name

music_tool = registry.get_by_capability("music_library")
result = music_tool.execute({})  # Empty dict uses default library_dir

```

The `execute()` method returns a `ToolResult` object containing a `tracks` array, where each element provides `name`, `path`, `size`, and optional `duration_seconds` fields.

## Asset Director Integration Stages

### Proposal Stage Surfacing

During the **proposal** step, every asset-director skill queries the `music_library` capability to enumerate available tracks before invoking any paid or API-based music generators. This satisfies the "no surprise at the asset stage" rule documented in [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md), allowing human reviewers to approve royalty-free options early in the workflow.

If `music_info["track_count"] > 0`, the director presents the discovered tracks—including metadata extracted by `_probe_duration()`—within the proposal interface. This early exposure prevents unnecessary API calls to services like Pixabay or MusicGen when suitable local assets exist.

### Asset Stage Manifest Integration

Upon user selection, the asset director handles the physical integration of the chosen track. According to the pipeline specifications in [`skills/pipelines/talking-head/asset-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/talking-head/asset-director.md) (and equivalent files for other pipeline types), the director performs two critical operations:

1. **File Ingestion**: Copies the selected track from the `music_library/` drop path into the project's `assets/audio/` directory using `shutil.copy2()`
2. **Manifest Recording**: Records the track in [`asset_manifest.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/asset_manifest.schema.json) with the `source_tool` field set to `"music_library"`

```python
import shutil
import pathlib

# Selected track from music_library.execute() result

chosen = tracks[selection_index]
proj_assets = pathlib.Path(project_root) / "assets" / "audio"
proj_assets.mkdir(parents=True, exist_ok=True)

# Copy to project assets

dest_path = proj_assets / "background_music.mp3"
shutil.copy2(chosen["path"], dest_path)

# Update manifest per asset_manifest.schema.json

manifest_entry = {
    "music": {
        "path": str(dest_path),
        "source_tool": "music_library",
        "duration_seconds": chosen["duration_seconds"]
    }
}

```

## Fallback Logic for Empty Libraries

When the drop folder is missing, empty, or contains no supported audio files, the asset director implements graceful degradation. As documented in [`skills/pipelines/explainer/asset-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/explainer/asset-director.md), the director falls back to generated music providers such as `music_gen` or `pixabay_music`:

```python
if not tracks:
    # No user tracks available - trigger fallback generation

    music_gen = registry.get_by_capability("music_gen")
    generated = music_gen.execute({"mood": "uplifting"})
    # Process generated track through same manifest pipeline

```

This ensures continuous background music availability while strictly preferring user-provided royalty-free assets when present.

## Summary

- The **music library drop path** resolves through environment variables, explicit configuration, or the default `music_library/` directory at the repository root
- `MusicLibrary._list_tracks()` recursively discovers audio files matching `_AUDIO_EXTENSIONS`, with optional duration probing via `_probe_duration()`
- The tool registers under the `music_library` capability in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py), accessible to all asset directors
- Asset directors query the library during the **proposal stage** to surface royalty-free options before API-based generation
- Selected tracks copy to `assets/audio/` and record in [`asset_manifest.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/asset_manifest.schema.json) with `source_tool: "music_library"`
- Empty libraries trigger automatic fallback to `music_gen` or `pixabay_music` providers

## Frequently Asked Questions

### What audio formats does the OpenMontage music library support?

The `MusicLibrary` tool in [`tools/audio/music_library.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/audio/music_library.py) maintains an internal whitelist `_AUDIO_EXTENSIONS` that includes standard formats such as MP3, WAV, and FLAC. The `_list_tracks()` method filters discovered files against this whitelist during the recursive directory scan, ensuring only compatible audio files appear in the asset director's selection interface.

### Can I store the music library folder outside the project root?

Yes. While the default location is `<project-root>/music_library`, you can override this by setting the `MUSIC_LIBRARY_DIR` environment variable or by passing an explicit `library_dir` parameter when executing the tool via `registry.get_by_capability("music_library")`. The `_library_dir()` method checks these sources in priority order before defaulting to the repository root folder.

### How does the asset director handle missing or empty music libraries?

If `music_library.execute()` returns zero tracks—either because the folder is missing, empty, or contains no supported formats—the asset director falls back to API-based music generation. According to the pipeline documentation in `skills/pipelines/*/asset-director.md`, the director automatically queries alternative capabilities such as `music_gen` or `pixabay_music` to ensure the video pipeline receives background music regardless of local asset availability.

### Where is the selected track stored after approval?

Once a user selects a track from the music library during the proposal or asset stage, the asset director copies the file into `assets/audio/` within the project workspace and updates the project's **asset manifest** ([`asset_manifest.schema.json`](https://github.com/calesthio/OpenMontage/blob/main/asset_manifest.schema.json)). The manifest entry includes the file path, duration metadata extracted by `_probe_duration()`, and the `source_tool` field set to `"music_library"` to maintain provenance records.