Backend Services External Integrations

External Integrations

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document explains the external service integrations powering the platform, focusing on:

• YouTube audio extraction and metadata retrieval
• Genius API lyrics retrieval with authentication, rate limiting, and fallback strategies
• Spleeter-based audio separation for source separation
• API key management and security
• Error handling for network failures, rate limits, and service unavailability
• Caching mechanisms and performance optimization
• Troubleshooting and monitoring approaches

Project Structure

The integration spans three primary areas:

• Frontend services for YouTube extraction and lyrics orchestration
• Python backend services for lyrics and audio separation
• Shared API key management and validation utilities

graph TB
subgraph "Frontend"
FE_YT["yt-mp3-go Service<br/>src/services/youtube/ytMp3GoService.ts"]
FE_YTDEV["yt-dlp Service (dev)<br/>src/services/youtube/ytDlpService.ts"]
FE_AUDIO_EXTRACT["Audio Extraction Orchestrator<br/>src/services/audio/audioExtractionSimplified.ts"]
FE_LYRICS["Lyrics Orchestrator<br/>src/services/lyrics/lyricsService.ts"]
FE_LRCLIB["LRClib Service<br/>src/services/lyrics/lrclibService.ts"]
FE_YTUTILS["YouTube Utils<br/>src/utils/youtubeUtils.ts"]
FE_APIKEY["API Key Storage<br/>src/services/cache/apiKeyStorageService.ts"]
FE_APIKEYVAL["API Key Validation<br/>src/services/api/apiKeyValidationService.ts"]
end
subgraph "Backend"
BE_GENIUS["Genius Service<br/>python_backend/services/lyrics/genius_service.py"]
BE_LYRICS_ROUTES["Lyrics Routes<br/>python_backend/blueprints/lyrics/routes.py"]
BE_SPLEETER["Spleeter Service<br/>python_backend/services/audio/spleeter_service.py"]
BE_DEMIX["Demix Spectrogram<br/>python_backend/models/Beat-Transformer/demix_spectrogram.py"]
BE_ERR["Error Handlers<br/>python_backend/error_handlers.py"]
end
FE_AUDIO_EXTRACT --> FE_YT
FE_AUDIO_EXTRACT --> FE_YTDEV
FE_AUDIO_EXTRACT --> FE_YTUTILS
FE_LYRICS --> FE_LRCLIB
FE_LYRICS --> BE_LYRICS_ROUTES
BE_LYRICS_ROUTES --> BE_GENIUS
FE_APIKEYVAL --> FE_APIKEY
BE_SPLEETER --> BE_DEMIX

Loading

Diagram sources

• ytMp3GoService.ts:1-204
• ytDlpService.ts:1-236
• audioExtractionSimplified.ts:657-799
• youtubeUtils.ts:1-65
• lyricsService.ts:1-197
• lrclibService.ts:1-266
• routes.py:1-126
• genius_service.py:1-215
• spleeter_service.py:1-286
• demix_spectrogram.py:41-70
• error_handlers.py:1-161

Section sources

• ytMp3GoService.ts:1-204
• ytDlpService.ts:1-236
• audioExtractionSimplified.ts:657-799
• lyricsService.ts:1-197
• lrclibService.ts:1-266
• routes.py:1-126
• genius_service.py:1-215
• spleeter_service.py:1-286
• demix_spectrogram.py:41-70
• error_handlers.py:1-161

Core Components

• YouTube audio extraction:
  • Production-grade extraction via a third-party proxy service with quality selection and format metadata.
  • Development fallback to a local yt-dlp service for local environments.
• Genius API lyrics:
  • Authentication via custom header or environment variable, with rate limiting and graceful fallback to LRClib.
• Spleeter audio separation:
  • On-demand separation with model selection, robust error handling, and cleanup.
• API key management:
  • Secure browser-side encryption and storage, validation service, and UI settings.

Section sources

• ytMp3GoService.ts:75-155
• ytDlpService.ts:38-235
• audioExtractionSimplified.ts:657-799
• genius_service.py:28-88
• routes.py:22-72
• spleeter_service.py:17-286
• apiKeyStorageService.ts:13-301
• apiKeyValidationService.ts:15-299

Architecture Overview

The system integrates external services through a layered approach:

• Frontend orchestrators call either the production YouTube extractor or the dev yt-dlp service.
• Lyrics retrieval prioritizes synchronized lyrics via LRClib, with Genius as a fallback.
• Backend routes expose endpoints for lyrics and delegate to specialized services.
• Spleeter runs in the backend for audio separation tasks.
• API keys are managed securely in the browser and validated centrally.

sequenceDiagram
participant FE as "Frontend"
participant AE as "Audio Extraction Orchestrator"
participant YT as "yt-mp3-go Service"
participant PY as "Python Backend"
participant LY as "Lyrics Orchestrator"
participant LR as "LRClib"
participant GI as "Genius Route"
FE->>AE : Request audio extraction
AE->>YT : Extract audio metadata and formats
YT-->>AE : Formats list (quality, size, URL)
AE-->>FE : Final audio URL and metadata
FE->>LY : Request lyrics
LY->>LR : Search synchronized lyrics
alt Found
LR-->>LY : Synced lyrics + metadata
else Not found
LY->>GI : Fallback to Genius (with API key)
GI-->>LY : Plain lyrics + metadata
end
LY-->>FE : Lyrics result

Loading

Diagram sources

• audioExtractionSimplified.ts:657-799
• ytMp3GoService.ts:87-155
• lyricsService.ts:72-172
• lrclibService.ts:32-145
• route.ts:40-80
• routes.py:22-72

Detailed Component Analysis

YouTube Integration

• Metadata extraction and audio formats:
  • The service posts a YouTube URL to a proxy endpoint, parses the response, filters audio items, and selects a preferred quality or falls back to the first available.
• Stream quality selection:
  • Preferred quality is configurable; the service chooses the matching format or the first one if none matches.
• Error handling:
  • Non-OK HTTP responses, missing audio items, and invalid URLs are handled with explicit error reporting.
• Development fallback:
  • The yt-dlp service provides local development support with health checks and filename compatibility.

sequenceDiagram
participant FE as "Frontend"
participant AE as "Audio Extraction Orchestrator"
participant YT as "yt-mp3-go Service"
participant FS as "Firestore Cache"
FE->>AE : Extract audio(videoId)
AE->>FS : Check cache
alt Cache hit
FS-->>AE : Cached metadata
AE-->>FE : Return cached result
else Cache miss
AE->>YT : POST extractAudio(youtubeUrl)
YT-->>AE : {formats, selectedAudio, metadata}
AE->>FS : Save metadata
AE-->>FE : Final audio URL and metadata
end

Loading

Diagram sources

• audioExtractionSimplified.ts:657-799
• ytMp3GoService.ts:87-155

Section sources

• ytMp3GoService.ts:75-155
• ytDlpService.ts:38-235
• audioExtractionSimplified.ts:657-799
• youtubeUtils.ts:14-65

Genius API Integration

• Authentication:
  • The backend reads the API key from a custom header forwarded by the frontend or from environment variables.
• Rate limiting:
  • Backend routes apply moderate-processing rate limits.
• Fallback strategies:
  • Frontend attempts backend route first; on failure or timeout, it falls back to direct Genius API call with a timeout.
• Error handling:
  • Centralized error handlers return structured JSON responses for common HTTP errors and custom exceptions.

sequenceDiagram
participant FE as "Frontend"
participant API as "Next.js API Route"
participant PY as "Flask Backend"
participant GI as "Genius Service"
FE->>API : POST /api/genius-lyrics
API->>PY : Forward with X-Genius-API-Key
PY->>GI : fetch_lyrics(artist,title,query)
alt Available
GI-->>PY : Success
PY-->>API : JSON result
API-->>FE : Success
else Unavailable
PY-->>API : Error
API-->>FE : Fallback to direct Genius
end

Loading

Diagram sources

• route.ts:40-80
• routes.py:22-72
• genius_service.py:28-88
• error_handlers.py:13-93

Section sources

• genius_service.py:14-215
• routes.py:22-126
• route.ts:40-80
• error_handlers.py:13-161

Spleeter Integration

• Supported models:
  • 2-stems, 4-stems, and 5-stems separation models are supported.
• Processing parameters:
  • Audio is loaded with librosa, normalized to stereo, and separated using the chosen model.
• Quality considerations:
  • Proper resource management and cleanup of temporary directories and files.
• Integration in downstream models:
  • Demixing functions leverage Spleeter for accurate spectrogram creation and include detailed error messaging for model cache issues.

flowchart TD
Start(["Start Separation"]) --> Load["Load audio with librosa"]
Load --> Stereo["Ensure stereo format"]
Stereo --> CreateSep["Create Spleeter separator"]
CreateSep --> Separate["Run separation"]
Separate --> Save["Save stems to disk"]
Save --> Cleanup["Cleanup temp dir/files"]
Cleanup --> End(["Return results"])

Loading

Diagram sources

• spleeter_service.py:71-286
• demix_spectrogram.py:41-70
• beat_transformer.py:586-714

Section sources

• spleeter_service.py:17-286
• demix_spectrogram.py:41-70
• beat_transformer.py:586-714

API Key Management and Security

• Secure storage:
  • Browser-side encryption using Web Crypto AES-GCM with PBKDF2-derived keys; sensitive data stored in localStorage with metadata.
• Validation:
  • Validation service caches results and exposes helper methods to check service eligibility and clear caches.
• UI integration:
  • Settings component allows adding/removing keys and displays validity status.

classDiagram
class ApiKeyStorageService {
+storeApiKey(service, key)
+getApiKey(service)
+hasApiKey(service)
+removeApiKey(service)
+getAllApiKeys()
+clearAllApiKeys()
+isEncryptionSupported()
}
class ApiKeyValidationService {
+validateMusicAiKey(key)
+validateGeminiKey(key)
+validateSongformerAccessKey(key)
+isEligibleForAppKey(service)
+clearValidationCache()
}
class ApiKeySettings {
+onApiKeyUpdate(service, key)
+handleRemoveKey(service)
}
ApiKeySettings --> ApiKeyValidationService : "uses"
ApiKeyValidationService --> ApiKeyStorageService : "reads/writes"

Loading

Diagram sources

• apiKeyStorageService.ts:13-301
• apiKeyValidationService.ts:15-299
• ApiKeySettings.tsx:10-40
• apiKeyTypes.ts:6-67

Section sources

• apiKeyStorageService.ts:13-301
• apiKeyValidationService.ts:15-299
• ApiKeySettings.tsx:1-40
• apiKeyTypes.ts:1-67

Dependency Analysis

• Frontend-to-backend dependencies:
  • Frontend lyrics orchestrator calls backend routes for Genius/LRClib; backend routes depend on specialized services.
• YouTube extraction:
  • Frontend extraction orchestrator defaults to browser yt-dlp with server finalization; local yt-dlp is used in development and yt-mp3-go is rollback-only.
• Spleeter:
  • Backend services depend on Spleeter and librosa; downstream models rely on demixing functions.

graph TB
FE_EX["audioExtractionSimplified.ts"] --> YTMP3["ytMp3GoService.ts"]
FE_EX --> YTDL["ytDlpService.ts"]
FE_LY["lyricsService.ts"] --> LRCL["lrclibService.ts"]
FE_LY --> BE_RT["routes.py"]
BE_RT --> GI["genius_service.py"]
BE_SPL["spleeter_service.py"] --> DEM["demix_spectrogram.py"]

Loading

Diagram sources

• audioExtractionSimplified.ts:657-799
• ytMp3GoService.ts:75-155
• ytDlpService.ts:38-235
• lyricsService.ts:72-172
• lrclibService.ts:32-145
• routes.py:22-126
• genius_service.py:14-215
• spleeter_service.py:17-286
• demix_spectrogram.py:41-70

Section sources

• lyricsService.ts:1-197
• routes.py:1-126
• spleeter_service.py:1-286

Performance Considerations

• Caching:
  • YouTube metadata is cached in Firestore to avoid repeated extractions and reduce latency.
• Timeout strategies:
  • Frontend Genius API route applies a 15-second timeout before falling back to direct API calls.
• Model availability:
  • Spleeter availability checks prevent unnecessary initialization and improve startup reliability.
• Resource cleanup:
  • Temporary directories and files are cleaned up after separation to avoid disk pressure.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

• YouTube extraction issues:
  • Verify the proxy endpoint returns OK and contains audio items; confirm the URL is valid and the preferred quality is available.
  • In development, ensure the yt-dlp service is healthy and reachable.
• Genius API issues:
  • Confirm the API key is present in the custom header or environment; check backend rate limits and centralized error responses.
  • If backend route fails, the frontend fallback to direct Genius API should still work with a timeout.
• Spleeter issues:
  • If separation fails, inspect logs for model cache problems and ensure the pretrained model is downloaded or copied into the expected cache directory.
• API key issues:
  • Confirm encryption support is available in the browser; check that keys are stored and retrievable; clear caches if validation results appear stale.

Section sources

• ytMp3GoService.ts:103-155
• ytDlpService.ts:178-214
• route.ts:40-80
• genius_service.py:28-88
• error_handlers.py:13-93
• spleeter_service.py:160-178
• apiKeyStorageService.ts:293-301

Conclusion

The platform integrates external services with a robust fallback strategy, strong error handling, and secure API key management. YouTube extraction leverages a production-friendly proxy with development fallback, Genius lyrics benefit from rate-limited backend routes and frontend fallback, and Spleeter provides reliable audio separation with careful resource management. Together, these components deliver a resilient and performant experience across varied environments.