# ZEYORA

> ZEYORA (https://zeyora.my.id) adalah aplikasi streaming musik berbasis web dan mobile PWA / Android APK bergaya modern Spotify tanpa iklan, dengan kurasi mendalam konten musik regional Indonesia, lirik berjalan sinkron real-time, dan fitur interaktif Duo Bucin Space untuk pasangan jarak jauh (LDR).

## Ringkasan Proyek
- Nama Aplikasi: ZEYORA
- Slogan: Music for your moment.
- Domain Resmi: https://zeyora.my.id
- Package ID Android APK: app.zeyora.music
- Bahasa Utama: Bahasa Indonesia (id-ID)
- Lisensi Penggunaan: Gratis / Bebas Iklan (Non-commercial community streaming)
- Target Audiens: Pecinta musik Indonesia, Gen Z, pendengar lagu galau, indie, dan pasangan LDR.

## Fitur Utama (Core Features)

1. Kurasi Musik Regional Indonesia
   - Feed beranda menyajikan konten asli Indonesia tanpa kontaminasi artis atau tangga lagu luar negeri:
     * Pilihan Cepat: Rekomendasi lagu cepat berdasarkan selera musik Indonesia.
     * Trending di Indonesia: Tangga lagu terpopuler tanah air (Bernadya, Sal Priadi, Tulus, Mahalini, Denny Caknan, Hindia, Sheila On 7, dll).
     * Hits & Playlist Indonesia: Kompilasi playlist terkurasi seperti Spotify Top Hits Indonesia, 100 Lagu Teratas Indonesia, dan Pop Indie Nusantara.
     * Artis Teratas Indonesia: Profil lengkap musisi dan grup musik papan atas Indonesia.
   - Algoritma pencarian dan penyaringan ketat bebas aksara asing/Indic script dan kata kunci non-Indonesia.

2. Web Audio Player & DSP Engine
   - Pemutaran audio jernih bertenaga HTML5 Audio dan Web Audio API.
   - Equalizer 3-band (Bass Low-shelf, Vocal Mid-peaking, Treble High-shelf) dengan Preamp Volume Boost hingga 150%.
   - Kontrol pemutaran lengkap: Shuffle, Repeat (Off, One, All), Kecepatan Putar (0.5x - 2.0x), dan Pengatur Waktu Tidur (Sleep Timer).
   - Dukungan audio latar belakang (background playback) dan integrasi MediaSession API untuk kontrol lock screen.

3. Lirik Berjalan Sinkron Otomatis (Real-time Synced Lyrics)
   - Lirik lagu tersinkronisasi per baris secara otomatis selaras dengan lantunan melodi.
   - Tampilan Fullscreen Lyrics Overlay dengan efek autoscroll dinamis dan tipografi modern yang mudah dibaca.

4. Duo Bucin Space (Sesi Musik Berpasangan LDR)
   - Ruang dengar bersama secara real-time untuk pasangan Gen Z dan pejuang jarak jauh (LDR).
   - Kode sesi unik 6 karakter (contoh: ZY-8K2P) dan tautan langsung pairing (?duo=KODE).
   - Sinkronisasi satu-klik lagu yang sedang didengar pasangan.
   - Penghitung hari jadian otomatis (Anniversary Days Counter).
   - Kalkulator jarak kilometer antar kota di Indonesia (Haversine Distance).
   - Playlist kolaboratif "Lagu Kita" dilengkapi catatan cinta (love note).
   - Kustomisasi tema warna ruang modern non-merah dan pengunggahan wallpaper ruang via VyDrive CDN.

5. Pustaka Lagu & Mode Offline
   - Manajemen playlist pribadi (Buat Playlist, Tambah Lagu, Susun Urutan).
   - Fitur Berbagi Playlist Cloud (Cloud Playlist Sharing) via tautan instan.
   - Mode offline memanfaatkan Cache Storage / IndexedDB untuk memutar lagu favorit tanpa koneksi internet.

6. Android APK & PWA Readiness
   - Dibangun dengan Capacitor 6 untuk Android native dengan dukungan background service, wake lock, dan post notifications.
   - Standar PWA responsif untuk ponsel (viewport 375px - 430px) hingga layar desktop (1280px+).
   - Zero Emojis Policy: Desain antarmuka bersih dan profesional tanpa emotikon/emoji.

## Struktur Rute & Navigasi (URL Structure)
- Beranda: https://zeyora.my.id/home
- Pencarian Katalog: https://zeyora.my.id/search?q={query}
- Pustaka Pengguna: https://zeyora.my.id/library
- Lagu Disukai: https://zeyora.my.id/liked
- Pemutaran Langsung: https://zeyora.my.id/play/{videoId}?title={judul}&artist={artis}
- Daftar Putar Berbagi: https://zeyora.my.id/shared-playlist/{shareId}
- Profil Pengembang: https://zeyora.my.id/dev

## Antarmuka Pemrograman Aplikasi (API Endpoints)
- GET /api/home : Mengembalikan 4 feed regional Indonesia (quickPicks, trending, playlists, artists).
- GET /api/search?query={q}&type={type} : Melakukan pencarian lagu, album, playlist, atau artis YouTube Music.
- GET /api/ytplay?id={videoId} : Mengambil URL stream audio langsung berbitrate optimal.
- GET /api/lyrics?videoId={videoId} : Mengambil lirik sinkron (synced) atau teks biasa (plain).
- POST /api/duo/create : Membuat sesi Duo Bucin baru dan menghasilkan kode 6 karakter.
- GET /api/duo/:sessionCode : Membaca status real-time pasangan pada sesi Duo Bucin.
- POST /api/duo/heartbeat : Mengirimkan pembaruan lagu dan detak jantung pasangan.
- POST /api/playlists/share : Menyimpan dan menghasilkan ID publik playlist kolaboratif.
- POST /api/upload : Mengunggah berkas gambar/wallpaper ke CDN VyDrive (multipart/form-data).

## Informasi Teknis & Tumpukan Teknologi
- Frontend: React 18, Vite 5, Tailwind CSS, Lucide React Icons, Motion (Framer Motion).
- Backend: Express.js (Node.js 20+), serverless-http, Axios, MongoDB Atlas Driver.
- Mobile Packaging: Apache Capacitor 6 (Android target SDK 34, min SDK 22).
- CI/CD Build: GitHub Actions (.github/workflows/build-apk.yml) untuk otomatisasi build debug APK.
- Hosting: Vercel Serverless Function & Express fallback.