Atmos Community API Documentation

A community-driven Dolby Atmos streaming portal for Agung Music.
Host: https://atmos-community.agungdev.com

Overview

The Atmos Community server allows trusted contributors to upload community-mixed Dolby Atmos tracks (E-AC3 / EC-3 codec in an MP4 container). Uploaded audio is automatically segmented into MPEG-DASH format via FFmpeg and served securely to the Agung Music Android app.

Security Model

All segment and manifest requests are protected by two independent mechanisms:

Mechanism Details
Header check Every request must include X-Requested-By: AgungMusicApp
HMAC-SHA256 token Every URL contains a ?token=<hmac>&expires=<unix_ts> query string. Tokens expire after 6 hours.
Referer block Direct browser access (with a foreign Referer header) is rejected with HTTP 403.
No directory listing The /dash/ folder is never exposed as a browsable directory.

This is not DRM — it does not use encrypted media. It is a robust access-control layer that makes casual scraping and direct-play from a browser effectively impossible.

Authentication

Upload API Key

All POST /upload requests must include:

X-Api-Key: <your_api_key>

Contact the server admin to obtain an upload API key.

App Request Header

All stream/segment requests from the Android app must include:

X-Requested-By: AgungMusicApp

Endpoints

GET /

Returns the HTML upload portal.

POST /upload

Submit a new community Atmos track for processing.

Headers:

X-Api-Key: <your_api_key>
Content-Type: multipart/form-data

Form fields:

Field Type Required Description
requester_name string ✅ Name of the person requesting the Atmos mix
song_name string ✅ Title of the song
artist string ✅ Artist name
duration float ✅ Duration in seconds
file file ✅ MP4 file with EC-3/E-AC3 audio codec

Response (201 Created):

{
  "id": "a1b2c3d4",
  "slug": "blue-bird-ikimono-gakari-a1b2c3d4",
  "mpd_url": "https://atmos-community.agungdev.com/stream/blue-bird.../manifest.mpd?token=...&expires=...",
  "song_name": "Blue Bird",
  "artist": "Ikimono-gakari",
  "requester_name": "Anakagung2009"
}

Error responses: - 401 — Invalid or missing API key - 400 — Invalid file type (only .mp4 / .m4a accepted) - 500 — FFmpeg processing error

GET /stream/{slug}/manifest.mpd

Retrieve the MPEG-DASH manifest for a track.

Required headers & query params:

X-Requested-By: AgungMusicApp
?token=<hmac>&expires=<unix_timestamp>

Response: application/dash+xml — the MPD manifest with signed segment URLs.

Tokens are refreshed automatically by the /songs API so the app always has a valid URL.

GET /dash/{slug}/{segment}

Stream an individual MPEG-DASH audio segment.

Required headers & query params:

X-Requested-By: AgungMusicApp
?token=<hmac>&expires=<unix_timestamp>

Response: video/mp4 — binary segment data.

GET /songs

List all community tracks. Returns fresh signed MPD URLs.

Query parameters:

Param Type Description
query string Filter by song name (case-insensitive)
artist string Filter by artist name (case-insensitive)
page int Page number (default: 1)
per_page int Results per page (default: 50, max: 50)

Response:

{
  "total": 3,
  "page": 1,
  "per_page": 50,
  "songs": [
    {
      "id": "a1b2c3d4",
      "slug": "blue-bird-ikimono-gakari-a1b2c3d4",
      "song_name": "Blue Bird",
      "artist": "Ikimono-gakari",
      "requester_name": "Anakagung2009",
      "duration": 171.0,
      "mpd_url": "https://atmos-community.agungdev.com/stream/.../manifest.mpd?token=...&expires=...",
      "uploaded_at": "2026-07-16T01:30:00Z"
    }
  ]
}

GET /songs/{track_id}

Get a single track by its 8-character ID.

Response: Same as a single item in the /songs list.

GET /docs

This documentation page (rendered from DOCS.md).

GET /health

Server health check.

{ "status": "ok", "service": "atmos-community", "timestamp": "2026-07-16T01:30:00Z" }

Android Integration

Stream Priority

When the Agung Music app resolves streams for a track, the community server is queried first:

  1. GET https://atmos-community.agungdev.com/songs?query=<song_name>&artist=<artist>
  2. If a match is found → play as ATMOS_COMMUNITY type (DASH MPD, ec-3 codec)
  3. If no match → fall back to existing Tidal / Qobuz / YT stream

Request Headers for Segments

ExoPlayer / Media3 must attach:

X-Requested-By: AgungMusicApp

This is injected via a custom DataSource.Factory in the Android player setup.

Atmos Dialog Attribution

When activeStreamType == "ATMOS_COMMUNITY", the Now Playing screen shows:

"This Dolby Atmos has been mixed by the community and the one who requested this song is [requester_name]"

The requester_name is fetched from /songs?query=<song_name> at playback time.

Deployment

Docker

cd backend/atmos_community
cp .env.example .env
# Edit .env with your secrets
docker compose up -d

Environment Variables

Variable Default Description
HMAC_SECRET (change me!) Secret key for signing URLs
UPLOAD_API_KEY (change me!) Admin key for uploads
BASE_URL https://atmos-community.agungdev.com Public base URL
TOKEN_TTL_SECONDS 21600 Token lifetime (6 hours)

[!WARNING]
Always change HMAC_SECRET and UPLOAD_API_KEY before deploying to production!

Nginx Reverse Proxy (example)

server {
    listen 443 ssl;
    server_name atmos-community.agungdev.com;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # Increase timeout for large file uploads
        proxy_read_timeout 300;
        client_max_body_size 500M;
    }
}

MPD Format

The generated MPD follows the MPEG-DASH ISOFF Main profile and includes:

This is compatible with ExoPlayer / Media3 on Android with EC-3 support enabled.

Atmos Community — Part of AgungDev