$ show spotiflacapp/SpotiFLAC-Extension
This repository contains the extension ecosystem for SpotiFLAC, a mobile application that downloads high-quality music from streaming services. The extensions are JavaScript modules that run in a sandboxed environment (vm.createContext) and implement service-specific adapters for providers like Amazon Music, Tidal, Qobuz, Deezer, Apple Music, and YouTube Music. Each extension exposes hooks such as search, download, handleUrl, and checkAvailability, and communicates with the host app via injected APIs (registerExtension, utils, session). The architecture is a set of isolated adapters with a shared pattern of quality fallback chains, retry logic with exponential backoff, metadata matching (ISRC, title, artist), and signed session authentication via a proxy API (api.zarz.moe). The primary data flow begins when a user provides a track URL or search query. The extension resolves the track metadata, checks availability (often via ISRC lookup or direct API calls), selects the highest available audio quality (e.g., Dolby Atmos, Hi-Res, Lossless), and initiates a download using signed tickets. The download process includes retry modes (poll_existing, new_ticket) and respects rate limits. The repository also includes a build script (scripts/build_packages.py) that creates reproducible .sflx archives and updates a central registry.json with SHA-256 digests for versioning and distribution. Key entry points are the source files in sources/<provider>/index.js, which contain the core business logic, and the corresponding manifest.json files that declare capabilities and permissions. The test files in tests/ demonstrate a sandbox testing pattern where host interfaces are mocked, allowing unit testing of fallback and matching logic. The repository is actively maintained with a community contribution model via pull requests, and the extension format is designed for easy addition of new streaming services.
The LLM identified 3 files worth highlighting for reuse:
Demonstrates a reusable pattern for testing sandboxed JavaScript extensions by creating a vm.Context with mocked log, utils, and session objects. Tests comprehensive fallback scenarios (quality downgrade, retry modes, verification propagation) and can be adapted to test any extension that follows the SpotiFLAC host API contract.
A self-contained Python script that builds .sflx extension packages from source files with deterministic zip settings (fixed timestamps, sorted entries). It updates registry.json with SHA-256 digests and supports --check mode for validation. This pattern is reusable for any project that needs to produce versioned, integrity-checked archives from a source directory.
Implements a robust retry helper (fetchWithRetry) with exponential backoff, jitter, and respect for Retry-After headers. Also handles regional URL normalization (e.g., music.amazon.co.uk to music.amazon.com) and ASIN remapping on 404 errors. The caching and retry patterns are generic and could be extracted for any API client that needs resilient HTTP calls.