================================================================================
PIRATERADIO BY EUGENIUSRO
Documentație Tehnică & Descrierea Aplicației
================================================================================
Download Link
1. PREZENTARE GENERALĂ (OVERVIEW)
——————————————————————————–
PirateRadio este o aplicație modernă pentru Android, dezvoltată nativ folosind
Kotlin și Jetpack Compose (Material 3). Aplicația combină un tuner radio online
avansat (alimentat de directorul deschis Radio-Browser) cu un player audio local
pentru fișiere MP3/audio stocate pe dispozitiv.
Aplicația oferă o experiență audio premium, optimizată pentru utilizare zilnică,
căști, boxe Bluetooth și sisteme auto (inclusiv suport pentru comenzi media
în mașină și compatibilitate cu servicii de fundal).
Caracteristici distinctive:
– Redare în fundal continuă prin Foreground Service & MediaSession.
– Egalizator vizual inspirat de clasicul Winamp cu analiză de spectru FFT
în timp real pe baza semnalului audio și mod Full-Screen interactiv.
– Buton dedicat de Shutdown / Oprire completă din aplicație.
– Butoane rapide de Preset P1-P5 dedicate pentru utilizare la volan (Car Mode).
– Reîncercare și reconectare automată la pierderea semnalului mobil/Wi-Fi.
– Audio Focus inteligent cu Ducking (reducerea discretă a volumului la indicațiile
GPS / Waze / apeluri).
– Temporizator de oprire (Sleep Timer 15m, 30m, 45m, 60m).
– Istoric al melodiilor difuzate (Recent Track History) extras automat din
metadatele ICY ale stream-urilor.
– 5 teme vizuale elegante (Neon Cyber, Retro Gold, Midnight Blue, Emerald, Sunset).
2. ARHITECTURA TEHNICĂ (ARCHITECTURE & TECH STACK)
——————————————————————————–
– Limbaj: Kotlin 2.2.10
– Toolkit UI: Jetpack Compose (Material 3) cu Compose Compiler modern
– Arhitectură software: MVVM (Model-View-ViewModel) + Repository Pattern + UDF
(Uni-directional Data Flow) folosind Kotlin StateFlow & Coroutines.
– Motor Audio: AndroidX Media3 (ExoPlayer 1.11.1) cu suport HLS, Shoutcast/Icecast,
MP3, AAC.
– Sesiune Media: AndroidX MediaSessionService + MediaController (compatibil
cu notificările de sistem Android 11 – Android 17+, lock screen controls
și Bluetooth AVRCP).
– Stocare & Persistență: SharedPreferences (JSON serializat) pentru Favorite,
Teme și Istoric melodii; Storage Access Framework / MediaStore pentru MP3 locale.
– Target SDK: Android 37 (Android 17) | Min SDK: 30 (Android 11).
3. STRUCTURA COMPONENTELOR & MODULELOR
——————————————————————————–
Pachet principal: eugeniusro.pirateradio
A. Stratul de Redare Audio (Player & Service):
– RadioPlaybackService.kt:
Serviciu de fundal (Foreground Service) de tip `mediaPlayback`. Gestionează
instanța unică de ExoPlayer, configurează atributele audio pentru muzică,
gestionează întreruperile Audio Focus (ducking pentru navigație GPS și
întrerupere la deconectarea căștilor prin `handleAudioBecomingNoisy`),
și expune `ACTION_STOP_SERVICE` pentru închiderea completă a procesului.
– PlaybackConnection.kt:
Puntea de legătură (Bridge) între UI și serviciul de fundal prin
MediaController. Se ocupă de:
* Transmiterea comenzilor de Play, Pause, Stop, Seek, Next, Previous.
* Urmărirea stării de buffer, poziție și durată.
* Extragerea metadatelor dinamice ICY (titlu melodie și artist difuzate live).
* Logica de Reconectare Automată (Auto-Reconnect) la erori de rețea.
– AudioVisualizerManager.kt:
Gestionează captura audio hardware prin `android.media.audiofx.Visualizer`
atașat la `audioSessionId`-ul ExoPlayer. Calculează spectrul de frecvențe
FFT pe 32 de benzi și forma de undă PCM pe 64 de eșantioane. Include un
motor dinamic de fallback dacă permisiunea audio lipsește sau este restricționată
de politicile hardware ale unor producători.
B. Stratul de Date & Repositories:
– RadioBrowserRepository.kt:
Interoghează API-urile publice distribuite Radio-Browser (cu servere multiple
de rezervă la nivel global). Permite căutarea după nume, țară, gen/tag
și filtrarea după bitrate (≤64k, 96-128k, ≥192k).
– CuratedStations.kt:
Colecție integrată de posturi de radio de înaltă calitate din România
și internaționale (Rock, Pop, Dance, Jazz, Ambient, etc.), disponibile
instantaneu fără timp de încărcare.
– FavoritesRepository.kt:
Memorează posturile favorite fixate (Pinned Favorites), limitate la 50
pentru performanță optimă, persistate local.
– HistoryRepository.kt:
Înregistrează automat ultimele până la 30 de piese detectate în timp real
pe posturile radio ascultate, cu posibilitate de ștergere.
– LocalAudioRepository.kt:
Scanează fișierele audio de pe dispozitiv prin MediaStore și Storage
Access Framework (SAF) pentru redarea albumelor și pieselor MP3 proprii.
C. Stratul de Interfață Utilizator (UI / Compose):
– MainActivity.kt:
Punctul de intrare în aplicație; configurează modul Edge-to-Edge și
solicită la nevoie permisiunea de runtime `RECORD_AUDIO` pentru vizualizator.
– MainAppScreen.kt:
Ecranul cadru (Scaffold). Conține bara superioară cu brand-ul
“PirateRadio by eugeniusro” și butonul de Shutdown, bara de navigare
inferioară (Radio, Favorites, Local MP3, Themes) și player-ul persistent.
– PlayerBar.kt (MiniPlayerBar & ExpandedPlayerDialog):
* MiniPlayerBar: Bara compactă de redare ancorată deasupra navigației;
include mini-egalizatorul animat, titlul, metadatele live, buton de Stop
și Play/Pause.
* ExpandedPlayerDialog: Ecran modal extins cu reglaj fin, copertă/disc vinil,
butoane favorite, control complet și acces rapid la vizualizator.
– VisualizerView.kt (MiniEqualizerBars & FullScreenVisualizerDialog):
* MiniEqualizerBars: Egalizor compact cu 6 bare sincronizate cu spectrul audio.
* FullScreenVisualizerDialog: Ecran complet stil Winamp, cu fundal întunecat,
metadate live și 3 moduri de afișare comutabile prin atingere:
1) Classic Spectrum Analyzer (bare verticale cu markere albe de vârf).
2) Oscilloscope Waveform (undă sinusoidală fluidă captată din PCM).
3) Cyber Neon Symmetrical (egalizator simetric de la centru spre margini).
– RadioScreen.kt:
Exploratorul de posturi: căutare text, filtre de gen și țară, bară de butoane
rapide Preset P1-P5 (Car Mode) și listă cu indicatori de calitate/bitrate.
– FavoritesScreen.kt:
Panoul posturilor favorite salvate de utilizator.
– LocalAudioScreen.kt:
Player pentru fișierele audio stocate pe telefon / card SD.
– SettingsScreen.kt:
Configurarea celor 5 teme vizuale, selectorul de Sleep Timer, istoricul
pieselor recente și informațiile despre aplicație.
4. PERMISIUNI ANDROID DECLARATE & JUSTIFICAREA LOR
——————————————————————————–
1. android.permission.INTERNET
– Necesară pentru streaming-ul audio online al posturilor radio și pentru
interogarea directorului Radio-Browser.
2. android.permission.ACCESS_NETWORK_STATE
– Folosită pentru a monitoriza starea conexiunii și a declanșa mecanismul
inteligent de reconectare când conexiunea la date revine.
3. android.permission.FOREGROUND_SERVICE & FOREGROUND_SERVICE_MEDIA_PLAYBACK
– Obligatorie pe Android 14+ (API 34+) pentru a rula serviciul audio în mod
legal și continuu când ecranul este stins sau când utilizatorul comută pe
altă aplicație / Waze.
4. android.permission.RECORD_AUDIO
– Utilizată exclusiv pentru clasa `android.media.audiofx.Visualizer` din
Android SDK, care necesită această permisiune de sistem pentru a extrage
spectrul de frecvențe FFT din fluxul audio redat. Aplicația NU înregistrează,
NU stochează și NU transmite niciun fel de înregistrări de voce sau microfon.
5. android.permission.READ_MEDIA_AUDIO (Android 13+) / READ_EXTERNAL_STORAGE (Android 11-12)
– Necesară exclusiv pentru funcționalitatea opțională a tab-ului “Local MP3”,
permițând utilizatorului să redea propriile fișiere audio stocate pe telefon.
6. android.permission.WAKE_LOCK
– Previne intrarea procesorului în deep sleep în timpul redării unui flux radio,
evitând întreruperile neplăcute ale sunetului.
7. android.permission.POST_NOTIFICATIONS
– Permite afișarea controalelor media interactive în panoul de notificări și
pe ecranul de blocare (Play, Pause, Stop, Nume melodie).
5. CONFORMITATE GOOGLE PLAY (POLICY COMPLIANCE & PRIVACY)
——————————————————————————–
– Confidențialitate (Data Safety):
Aplicația PirateRadio NU colectează date personale, NU creează conturi de
utilizator, NU conține module de urmărire (trackers) sau SDK-uri de reclame invazive.
– Toate preferințele (stații favorite, teme, istoric piese) sunt stocate
strict local pe dispozitivul utilizatorului (Sandbox SharedPreferences).
– Trafic de rețea: Aplicația accesează doar stream-urile audio publice alese
de utilizator și API-ul deschis Radio-Browser.
– Închidere completă și control transparent: Aplicația include buton de oprire
definitivă (Shutdown) care eliberează imediat toate resursele hardware și de fundal.
================================================================================
Dezvoltator: eugeniusro
Aplicație: PirateRadio
Versiune: 1.0 (Build Code 1)
================================================================================
