# Radio Picla — Technical Documentation, Deployment & Deep-Dive Manual
> Comprehensive guide for developers, AI agents, and platforms on the multi-platform audio streaming architecture of Radio Picla.

- **Official Website:** [https://radio.picla.net](https://radio.picla.net)
- **Project Type:** Cross-Platform Web Radio Ecosystem
- **Engineering & Ownership:** Dario Passariello / BigLogic Inc.
- **Target Ecosystems:** Standard Web, Browser Extensions, Progressive Web Apps (PWA), Android Trusted Web Activities (TWA)
- **Version:** 1.0.0 (2026)

---

## 1. Architectural Overview & System Design
Radio Picla is engineered as a decoupled, modern digital audio distribution system. Rather than relying on heavy monolithic client applications or resource-intensive native runtimes, the platform leverages advanced web APIs to deliver high-fidelity background audio streaming across a dynamic, three-tiered cross-platform model.

### 1.1 Core Philosophy
- **Zero Friction:** No mandatory user registration, no complex on-boarding flows. Streaming initializes on a single input trigger.
- **Resource Minimalism:** Negligible CPU, RAM, and battery impact across desktop and mobile devices via heavily optimized event-driven code.
- **Continuous Session State:** Designed to maintain context, playback synchronization, and accessibility options across varied computing contexts.

### 1.2 Tech Stack Elements
- **Audio Delivery Engine:** Low-latency HTTP Live Streaming (HLS) / Icecast / Shoutcast compatible stream handling with robust buffer-underrun handling.
- **Frontend Architecture:** Vanilla modern JavaScript / Web Components, ensuring minimal bundle sizes and instant parsing times without the framework overhead of heavy virtual DOM trees.
- **Style Layers:** Micro-CSS utilizing semantic variables, fully supporting seamless switching between standard, high-contrast, dark, and light user interfaces.

---

## 2. Platform Component Implementations

### 2.1 Browser Extension Architecture
The Radio Picla Browser Extension allows users to control their audio workflow without keeping an active web tab open, bypassing aggressive browser tab-sleeping algorithms.
- **Background Script / Service Worker:** Operates as an event-driven background process. It hosts the HTML5 `Audio` context instance, keeping the audio thread alive even when standard web tabs are force-closed or put to sleep by the operating system.
- **Popup UI (`popup.html` / `popup.js`):** A lightweight, context-menu panel displaying current track metadata, album art, volume controls, and channel switching. Communicates with the background service worker using message-passing interfaces (`chrome.runtime.sendMessage`).
- **Global Keybinding Integration:** Registers custom command shortcuts within the browser environment. Users can play, pause, or mute via global operating system hotkeys mapped to the browser extension runtime.

### 2.2 Progressive Web App (PWA) Implementation
The PWA variant bridges the gap between traditional browser tabs and true native desktop/mobile software applications.
- **Service Worker Lifecycle:** Implements a strict offline caching policy for static assets (icons, layouts, core scripts) while allowing proxy pass-throughs for real-time audio bitstreams.
- **Web App Manifest (`manifest.json`):** Configured for a full-screen, immersive standalone experience (`"display": "standalone"`). Dictates orientation constraints, branding palettes, and app shortcuts for deep-linking capability directly from the device's application launcher.
- **Caching & Storage Strategy:** Uses the Cache Storage API to store UI structures and user preferences, achieving near-instantaneous load times (First Contentful Paint < 500ms) even on restricted 3G mobile networks.

### 2.3 Android Trusted Web Activity (TWA) Wrapper
For the Android ecosystem, Radio Picla uses a Trusted Web Activity container to publish directly to the Google Play Store while maintaining single-codebase velocity.
- **Digital Asset Links Validation:** Utilizes a secure, bi-directional verification protocol (`assetlinks.json`) hosted on `radio.picla.net/.well-known/assetlinks.json`. This proves ownership to the Android OS, completely removing the browser URL address bar and offering a true full-screen native app container.
- **Native Custom Tabs Integration:** Utilizes a custom-tailored Android implementation based on Google Custom Tabs, inheriting optimized rendering speeds, Shared Cookie Jars, and full Chrome engine performance enhancements.
- **Hardware Integration:** Connects web-based events directly into the Android system's media session routing, allowing system-level Bluetooth inputs, locking screen widgets, and Android Auto interfaces to interact with the audio stream flawlessly.

---

## 3. Key Advanced Web API Integrations

### 3.1 Media Session API
Radio Picla deeply integrates with the `navigator.mediaSession` API to expose rich metadata to the underlying host platform's hardware and notification centers.

```javascript
if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Current Live Track',
    artist: 'Radio Picla Station',
    album: 'The Next-Generation Digital Audio Experience',
    artwork: [
      { src: 'https://radio.picla.net/logo.png', sizes: '512x512', type: 'image/png' }
    ]
  });

  navigator.mediaSession.setActionHandler('play', () => { /* Play Logic */ });
  navigator.mediaSession.setActionHandler('pause', () => { /* Pause Logic */ });
}