mirrors/onthespot
2
1
Fork 0
mirror of https://github.com/justin025/onthespot.git synced 2026-09-17 12:48:48 -07:00
Code Issues Projects Releases Packages Wiki Activity
Page: Overview
Pages
CLI Configuration File Docker 2.0 Setup on windows GUI Home Install Integrations Overview USAGE WebUI variables
1 Overview
0x4B1D edited this page 2026-09-13 06:10:13 +02:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

OnTheSpot (OTS) User Guide (fastapi-dev / v2.x)

Table of Contents

  1. Introduction
  2. Troubleshooting
  3. Usage & Installation
  4. Audio, Codecs, File Types & More
  5. Additional Resources

1. Introduction

1.1. What is OnTheSpot?

OnTheSpot (OTS) is a music downloader designed to search for and download tracks, albums, playlists, podcasts, and audiobooks directly from multiple streaming platforms.

In the fastapi-dev (v2.x) branch, the project transitioned away from legacy desktop Qt frameworks toward a modern, headless client-server architecture. The core engine is built as an asynchronous FastAPI backend paired with a reactive Web UI, enabling headless server/NAS operation, automated pipelines via REST endpoints, and simplified cross-platform deployment.

1.2. Architecture & Supported Platforms

The fastapi-dev branch is Docker-Native:

  • Docker / Containers (Recommended): Runs anywhere Docker runs—Windows (WSL2), macOS, Linux distributions, Unraid, TrueNAS, and home servers. All system dependencies (including FFmpeg) are pre-packaged, eliminating OS-specific path and build errors.
  • Web-Based: Accessed via any standard desktop or mobile web browser.
  • Headless & Automation: Features an interactive OpenAPI backend (accessible at /docs) for direct API calls, scripting, and third-party integrations.

1.3. Audio Quality

  • Downloads media at the source’s highest permissible quality (up to 24-bit / 192 kHz on lossless services).
  • Quality depends entirely on the service used and your account tier (Free vs. Premium).
  • File conversions and post-processing are handled seamlessly via container-embedded FFmpeg without requiring manual system configuration.

1.4. Is OnTheSpot Free?

Yes. OnTheSpot is an open-source project distributed for personal, non-commercial, and fair-use educational purposes.

1.5. Getting Started (Quick Setup)

The primary way to run the fastapi-dev branch is via Docker Compose:

# 1. Clone the fastapi-dev branch
git clone --branch fastapi-dev --single-branch https://github.com/ots-downloader/onthespot.git
cd onthespot

# 2. Start the container stack
docker compose up -d

Once started:

  • Open your browser to the Web UI at: http://localhost:5000 (or the port defined in your compose file).
  • Access interactive REST API documentation at: http://localhost:5000/docs.

2. Troubleshooting

2.1. Items Won’t Download

  • Check Account Session: Many services require a valid session or authentication cookies/tokens. In the Web UI, go to Settings > Accounts and verify your credentials (credentials are encrypted at rest using a Fernet key store).

2.2. Multiple Items Failing & Download Delays (Rate Limiting)

Streaming providers enforce rate limits when requests occur in rapid succession.

  • Wait Out Temporary Blocks: If rate-limited, wait 15–30 minutes before triggering Retry Failed in the Web UI.
  • Configure Download Delays: Go to Settings and raise the Download Delay (seconds):
    • 1–5s: Batches of 1–2 albums
    • 5–15s: Batches of 3–7 albums
    • 20–25s: Bulk queues of ~300+ tracks
    • 30s+: Large library migrations (~1,000+ tracks)
  • OTS v2.x features improved request pacing and respects HTTP Retry-After response headers automatically.

2.3. Items Say “Unavailable”

  • Region Restrictions: The item may not be licensed in your account’s registered country/region.
  • Tier-Gated Content: Audiobooks, MQA/Hi-Res tracks, or specific albums might require active paid subscriptions or platform purchases.
  • Removed Catalog Entries: If a song is greyed out on the provider’s native client, OTS cannot fetch it.

2.4. Account Requirements

Service Free Account Premium Account Required
Apple Music ❌ Not supported Required
Tidal ❌ Not supported Required (HiFi / HiFi Plus)
Qobuz ❌ Not supported Required
Spotify ❌ Not supported Required for 320 kbps & Audiobooks
Deezer Supported (128 kbps MP3) Required for 1411 kbps FLAC
YouTube / YT Music Supported (Opus/M4A) Optional (higher bitrates / no ads)
Soundcloud Supported (MP3/OGG) Required for HQ 256k AAC (Go+)
Bandcamp Supported (Public streams) Optional

2.5. My Problem Isn’t Listed & Accessing Logs

Because OTS v2.x runs a web/container architecture, you no longer need to scour hidden OS cache directories:

  1. In the Web UI: Navigate to the Logs tab to view real-time log outputs or download the active log file directly.
  2. Via Docker: Run: 
    docker compose logs -f
  3. Submitting an Issue / Support Request:
    • Open a ticket on GitHub Issues or the Discord #support channel.
    • Include:
      • Branch / Git commit hash (fastapi-dev).
      • Deployment type (Docker, Docker on Unraid/Synology, or native Python).
      • Browser and OS host details.
      • Relevant sanitized logs from the Logs screen.

3. Usage & Installation

Check the fastapi-dev branch specific INSTALLATION file in the docs folder.

4. Audio, Codecs, File Types & More

4.1. Terminology

  • Bitrate (kbps): Number of kilobits processed per second. Higher bitrates preserve more audio data.
  • CBR (Constant Bitrate): Applies an unvarying bit rate across the entire duration.
  • VBR (Variable Bitrate): Automatically increases bits during complex passages and decreases them during quiet sections for optimal efficiency.
  • Container (File Format): The outer file wrapper indicated by its extension (e.g., .mp3, .m4a, .flac, .ogg).
  • Codec: The mathematical scheme used to compress and decompress the audio stream (e.g., AAC, Opus, FLAC, Vorbis).
  • Sample Rate (Hz/kHz): How many times audio is sampled per second. Standard CD-quality audio is sampled at 44.1 kHz (44,100 samples/sec).
  • Lossless: Bit-for-bit recreation of original studio/CD masters without data discard (e.g., FLAC, ALAC, WAV).
  • Lossy: Algorithmic discarding of frequencies less discernible to the human ear to minimize file size (e.g., MP3, AAC, Opus).
  • Transcoding / Converting: Decompressing an audio stream and re-encoding it into a different format.

4.2. Getting the Highest Quality File

  1. Identify your provider on the Service, Bitrate, Container Table.
  2. Note the native format corresponding to your subscription level (Free vs. Premium).
  3. Set your target Track Format in OTS Profile to match the native format used by the streaming service.
  4. Direct Stream Copy: If your chosen Track Format matches the provider's original delivery format, OTS writes the file directly to disk without transcoding, eliminating possible quality loss and speeding up downloads.

Tip: Enable the Raw Media Download or Prefer Best Source Format toggle in Settings if you want to bypass conversions entirely and keep the exact byte-stream supplied by the remote CDN.

4.3. High-Resolution Audio

  • The majority of listeners cannot distinguish standard 320 kbps lossy (MP3/AAC) from 1411 kbps 16-bit / 44.1 kHz CD lossless audio in blind ABX testing.
  • True Hi-Res Audio (24-bit, 96–192 kHz) requires a dedicated Digital-to-Analog Converter (DAC), clean amplification, and capable wired headphones or studio monitors.
  • If you have an active HiFi/Master-tier plan on supported platforms (such as Tidal or Qobuz), setting your format target to FLAC will retrieve full-resolution streams without downsampling.

4.4. How to Play at the Highest Quality Over Bluetooth

Bluetooth transmissions are bandwidth-constrained; uncompressed 1411 kbps lossless playback cannot be streamed over standard Bluetooth connections:

  • Windows Default: Typically defaults to SBC or AAC (capped at ~256–320 kbps).
  • Android: Can transmit via LDAC (up to 990 kbps) or aptX HD/Adaptive if both your phone and headphones support the codec. Verify this under Developer Options > Bluetooth Audio Codec.
  • Car Consoles / Receivers: Usually limited to SBC or standard AAC.

4.5. What Determines Final Quality?

  1. Source Tier: You cannot extract higher quality than your account subscription permits.
  2. Settings Configuration:
    • Transcoding a lossy file (e.g., 160 kbps OGG from a free account) into a lossless container (.flac) will not restore lost fidelity; it only creates an artificially large file.
    • For maximum fidelity, match OTS's target format to the native stream container to avoid generational loss from re-encoding.

4.6. Service, Bitrate, Container Table

Service Free Format Premium / Paid Format
Apple Music N/A 256 kbps AAC (.m4a) *
Bandcamp 128 kbps MP3 N/A (Standard public stream)
Deezer 128 kbps MP3 1411 kbps FLAC (16-bit / 44.1 kHz)
Qobuz N/A Up to 24-bit 192 kHz FLAC
Soundcloud 128 kbps MP3 / 64 kbps Opus 256 kbps AAC (.m4a)
Spotify 160 kbps Vorbis (.ogg) 320 kbps Vorbis (.ogg)
Tidal N/A 1411 kbps FLAC / Hi-Res FLAC
YouTube / YT Music ~128 kbps Opus / AAC (.m4a) ~256 kbps Opus / AAC
Generic / Direct Varies by source Varies by source

* Note: Apple Music Lossless (ALAC) is protected by proprietary FairPlay DRM and is not retrievable without DRM decryption keys.

4.7. Supported File Formats in OTS

Because OTS delegates transcoding tasks to FFmpeg inside its execution environment, it can convert downloads into any format supported by FFmpeg:

  • Common Lossy: .mp3, .m4a (AAC), .ogg (Vorbis), .opus
  • Common Lossless / Uncompressed: .flac, .wav, .alac

When should you transcode?

  • Hardware Limitations: When legacy vehicle stereos or portable media players only recognize .mp3.
  • Storage Constraints: Downsampling high-bitrate libraries when syncing to mobile devices with limited storage.

5. Additional Resources

Footer