Songs Explorer

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/songs.ts
• tests/commands/songs.test.ts
• src/client.ts
• src/bin.ts
• src/output.ts
• CLAUDE.md

Songs Explorer is a specialized module within the Recoup CLI designed to facilitate the analysis and exploration of musical content. It serves as a bridge between local users and the Recoup platform's AI-driven analysis engines, allowing developers and curators to extract metadata, mood tags, and comprehensive reports from audio files.

The system is built upon the commander framework and interacts with the Recoup REST API. It supports both high-level "presets" (pre-defined analysis configurations) and "custom prompts" for granular control over the analysis output. It integrates with other system features like Artists and Tasks to provide a unified workflow for content management.
Sources: src/commands/songs.ts:1-74, src/bin.ts:13-25, CLAUDE.md:1-20

Architecture and Command Structure

The Songs Explorer is registered as a subcommand group under the main recoup binary. It encapsulates two primary operations: analyze for performing music AI tasks and presets for discovering available analysis capabilities.

The diagram below illustrates the command hierarchy and the relationship between the CLI and the backend API:

The CLI uses a central HTTP client to handle authentication via x-api-key and path resolution using a base URL defined in the environment.
Sources: src/bin.ts:13-25, src/commands/songs.ts:76-80, src/client.ts:7-45

Music Analysis (analyze)

The analyze command is the core functional component of the Songs Explorer. It allows users to send audio URLs or text-based metadata to the Recoup API for processing. Users must provide either a --prompt or a --preset to define the nature of the analysis.

Execution Flow

The following sequence diagram details the interaction during a typical analysis request:

Command Options

Option	Type	Description
--prompt	string	Custom text prompt for specific analysis needs.
--preset	string	Name of a curated analysis preset (e.g., catalog_metadata, full_report).
--audio	string	Public URL to an audio file (MP3, WAV, FLAC).
--max-tokens	integer	Maximum tokens to generate in the response (default: 512).
--json	boolean	Forces raw JSON output instead of formatted reports.

Sources: src/commands/songs.ts:6-12, tests/commands/songs.test.ts:47-59

Preset Management (presets)

Presets provide a way to standardize analysis across different tracks. The presets command retrieves a list of available configurations supported by the platform.

Preset Attributes

When listing presets, the CLI displays several metadata fields for each available option:

• Name: The identifier used with the --preset flag.
• Description: A summary of what the analysis entails (e.g., "Catalog enrichment").
• Requires Audio: A flag indicating if an --audio URL is mandatory.
• Response Format: Indicates if the result will be json or text.

Sources: src/commands/songs.ts:54-70, tests/commands/songs.test.ts:117-130

Data Processing and Output Formatting

The module handles three distinct response types from the API, providing specific formatting for each to ensure human readability:

1. Full Reports: When the API returns a report object, the CLI iterates through each section (e.g., "Lyrics Analysis", "Production Notes"), printing them with headers separated by double lines (=).
2. JSON Presets: If the response is a standard JSON object, it is "pretty-printed" using indentation.
3. Text Responses: Standard string responses are printed plainly, followed by the elapsed time in seconds.

// Example of the Report processing logic in src/commands/songs.ts
if (data.report) {
  const report = data.report as Record<string, unknown>;
  for (const [key, value] of Object.entries(report)) {
    console.log(`\n${"=".repeat(50)}`);
    console.log(`  ${key.toUpperCase().replace(/_/g, " ")}`);
    console.log(`${"=".repeat(50)}`);
    // ... value printing logic
  }
}

Sources: src/commands/songs.ts:28-50, src/output.ts:1-25

Error Handling

The module utilizes a centralized error handling strategy. Failures in the API (such as 401 Unauthorized or 400 Bad Request) or network issues are caught in the command's action block. The printError utility is then used to log the message to stderr and terminate the process with an exit code of 1.

Sources: src/commands/songs.ts:51-53, src/output.ts:47-55, src/client.ts:37-43

Summary

Songs Explorer provides a powerful interface for music data enrichment within the Recoup ecosystem. By abstracting the complexities of the /api/songs endpoints into simple analyze and presets commands, it allows for both automated batch processing via --json flags and manual curation through formatted text reports.
Sources: src/commands/songs.ts:1-80, CLAUDE.md:15-25