Decoupled Media Streams: A Django and Nextcloud Radio Architecture

The Problem – Adding Radio Without Turning Django Into a Proxy

Our platform already handled authentication, farm management, NDVI pipelines, weather ingestion, API‑key orchestration and a suite of Nextcloud integrations. The new requirement was to surface internet radio stations inside the Nextcloud UI. The naive solution would have been to let Django fetch the audio stream from BBC, SomaFM, or TuneIn, then pipe it back to the client. That approach would have introduced several issues:

• Bandwidth blow‑up – every concurrent listener would consume a full audio stream on the Django host, quickly saturating network and CPU.
• Latency inflation – an extra hop adds buffering and jitter, degrading the listening experience.
• State‑management complexity – the API would need to track per‑user stream lifecycles, retries, and error handling, turning a simple metadata service into a media server.

The architectural constraint was clear: Django must remain a pure metadata orchestrator. All heavy media transport should bypass the backend entirely.

---

Solution Approach – Split the Responsibility Chain

1. Metadata‑only API (Django + DRF)

• Endpoints – /api/v1/radio/ exposes station lists, stream URLs, thumbnails, and user‑specific flags (favorite, last‑played).
• Consistency model – the API is eventually consistent for user‑specific data (favorites, play counts). Core station catalog is read‑only and strongly consistent because it is refreshed from providers on a scheduled job.
• Caching – station metadata is cached in Redis with a TTL of 5 minutes; this reduces provider polling while keeping the catalog fresh.

2. Direct Stream Playback (Nextcloud Clients)

• The JSON payload from the API contains the original provider URL (e.g., https://stream.bbc.co.uk/...).
• Nextcloud’s web UI or desktop client opens that URL directly in an HTML5 <audio> element or native player, avoiding any backend hop.
• Authentication is handled by the provider (public streams) or by signed, time‑limited URLs generated by a lightweight signing service when a provider requires a token.

3. Integration Layer in Nextcloud

• A custom Nextcloud app registers a new dashboard widget that calls the Django API, renders the station list, and wires the <audio> tags to the returned URLs.
• The widget respects Nextcloud’s existing auth token, so the API call is already authorized – no extra login flow is needed.

Trade‑offs and Design Decisions

Aspect	Chosen Design	Alternative (Proxy)	Why the Choice
Scalability	Backend only serves JSON; streaming load is borne by provider CDNs.	Backend would need to scale horizontally to handle each concurrent audio stream.	Reduces required compute and network bandwidth by orders of magnitude.
Consistency	Station catalog is strongly consistent; user‑specific data is eventually consistent via async write‑behind to PostgreSQL.	Proxy would need strong transactional guarantees for every play event, complicating the data model.	Acceptable to tolerate slight delay in favorite/play‑count updates; UI can optimistically update.
Latency	Direct client‑to‑provider path eliminates extra hop, keeping latency under 200 ms typical for CDN streams.	Extra hop adds ~100‑200 ms round‑trip plus buffering.	Listening experience is highly sensitive to latency spikes.
Security	Provider URLs are either public or signed with short‑lived HMAC tokens.	Proxy could enforce auth centrally but would need to decrypt and re‑encrypt streams, increasing attack surface.	Token signing is simple, auditable, and revocable without touching the media path.
Future Extensibility	Adding a new provider is just a new entry in the metadata refresh job.	Proxy would require new ingestion pipelines and possibly transcoding.	Keeps the system modular; new features (favorites, podcasts) plug into the metadata layer only.

When a Proxy Might Still Be Viable

• Geo‑restricted streams where the provider only allows playback from certain IP ranges – a regional proxy could satisfy compliance.
• Analytics that require per‑second listening metrics – a lightweight proxy can emit fine‑grained events, but it re‑introduces bandwidth concerns.
• Content‑type transformation (e.g., converting AAC to Opus for mobile) – only needed if the client cannot handle the source codec.

In those niche cases, a dedicated streaming microservice (perhaps built with Go or NGINX‑RTMP) could be introduced without touching the existing Django API.

---

How This Architecture Supports Future Growth

1. Personalized Stations & Favorites – Store user‑station links in a separate table; the API merges them into the catalog on request. No change to the streaming path.
2. Listening History – Emit a fire‑and‑forget event to a Kafka topic when the client fires a play event; downstream consumers can build analytics pipelines.
3. Podcast Aggregation – Treat podcasts as stations with an RSS feed URL; the metadata service parses the feed and returns episode URLs, still streamed directly.
4. Recommendation Engine – Feed the same Kafka topic into a ML model that writes back suggested stations to the metadata store.
5. Multi‑provider Federation – Add a new refresh job that pulls stations from additional APIs (e.g., Icecast directories). The core API remains unchanged.

Because the backend never touches the media payload, scaling the system means only adding more workers for the periodic metadata refresh or more consumers for analytics – not provisioning high‑throughput media servers.

---

Closing Thoughts

The key insight was to recognize the boundary between orchestration and transport. By keeping Django focused on what to play rather than how to deliver the audio, we preserved the performance characteristics of an existing, heavily loaded platform while still delivering a seamless radio experience inside Nextcloud.

If you are building any feature that involves large binary blobs (media, backups, logs), ask yourself whether the backend truly needs to touch the payload. Often the answer is no, and the resulting architecture is simpler, cheaper, and more resilient.

---

For a deeper dive into tracing the request flow across these services, see the Sentry tutorial on distributed tracing.