I recently added a radio integration to a platform built around Django REST Framework (DRF), and Nextcloud.
The existing architecture was already doing a lot of heavy lifting, powering authentication, farm management, NDVI processing pipelines, weather data ingestion, API key orchestration, and Nextcloud application integrations.
The new requirement was to introduce internet radio support seamlessly inside the Nextcloud ecosystem. However, there was a strict architectural constraint: we needed to do this without turning Django into a media relay.
That single distinction shaped the entire implementation strategy.
The Core Challenge: Avoiding the Proxy Trap
Instead of proxying heavy audio streams through the backend, the architecture relies on direct playback. Django is strictly responsible for exposing radio metadata and playback endpoints (routed under /api/v1/radio/). Meanwhile, the Nextcloud clients stream the audio directly from the source providers, such as BBC, SomaFM, and TuneIn.
The result is a much cleaner separation of responsibilities:
Nextcloud UI / Web Client: The presentation layer.
Django + DRF API: Radio metadata and stream information logic.
Radio Providers: Direct playback of media transport.
Architectural Separation in Action
The following diagram illustrates exactly how we achieved this decoupling. The critical path is that thick dark orange arrow (3), showing the media stream bypassing the Django API server entirely.
(Diagram: Metadata requests [blue] are routed through Django, while heavy media streams [orange] flow directly from providers like BBC/SomaFM to the Nextcloud user.)
This separation keeps the backend highly performant and lightweight, while allowing the Nextcloud frontend to integrate radio discovery naturally alongside the rest of the platform's services.
How Nextcloud Fits Into the Architecture
The radio integration was explicitly designed to plug into a broader, Nextcloud-driven ecosystem rather than operating as an isolated, standalone media application. By defining strict boundaries, each system handles what it does best.
Nextcloud provides:
The frontend user experience
Authenticated user workflows
App integration surfaces and dashboard presentation
Native media interaction capabilities
Django provides:
API orchestration and provider abstraction
Station metadata and stream discovery
Data normalization logic
Backend consistency
This clear separation creates a strong boundary between backend platform orchestration and frontend client experience. Instead of embedding complex streaming logic directly into Nextcloud—or forcing Django to waste resources proxying media—the architecture keeps each layer focused entirely on its primary responsibility.
Built for Future Expansion
Because the backend already behaves like a pure metadata platform rather than a streaming server, the architecture leaves massive room for future expansion.
Without needing to redesign the streaming layer itself, this setup easily supports adding:
Personalized stations and user favorites
Listening history tracking
Podcast aggregation
Recommendation systems
Analytics pipelines
Multi-provider federation
By treating media transport and metadata orchestration as two distinct problems, the integration remains scalable, fast, and ready for whatever features the platform requires next.
Top comments (0)