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

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

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, 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 (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 with the source_tool field set to "music_library"

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, the director falls back to generated music providers such as music_gen or pixabay_music:

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, 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 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 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}