Livil

A social music platform — where listening is something you do together.

Spotify’s player · Discord’s presence · SoundCloud’s creator feed — in one app.

---

What is Livil?

Most music apps are something you use alone. Livil is built around the opposite idea: music is social.

Creators upload their tracks (audio and video). Listeners follow each other, see what friends are playing in real time, drop into Jam Rooms to listen in sync, build collaborative playlists, react and comment, and share clipped highlights as Stories and reposts — all wrapped in a polished, dark, gesture-driven mobile experience with full lock-screen media controls.

It’s a creator network, a listening party, and a chat app fused into a single React Native codebase running on the New Architecture (Fabric).

By the numbers: ~37,500 lines of TypeScript · 28 screens · 40+ reusable components · 21 backend services · 30+ database migrations · live on the App Store, Google Play, and the web.

---

📱 Screenshots

Home Feed	Full-Screen Player	Jam Room	Profile
Personalized feed with friends’ stories & reposts	Video + audio playback, shuffle / loop, lyrics & queue	Listen together in real time — synced + in-room chat	Creator profile: reposts, uploads, albums & playlists

🔒 Background & Lock-Screen Media Controls

A single audio engine drives full OS media-session controls — they keep working with the app backgrounded or the phone locked.

In-App Info & Credits	Notification Shade	Lock Screen

---

✨ Features

🎧 Listening & Playback

• Unified player engine for every post — audio tracks and the audio of video posts play through one source of truth.
• Lock-screen & notification media controls (play / pause / seek / next / prev) that keep working while the app is backgrounded — driven natively for reliability.
• Clip-aware playback — posts can play a clipped window of a track, with the lock-screen scrubber showing the clip, not the whole file.
• Beat-synced waveform visualizer — the floating player’s wave reacts to the song’s actual loudness and frequency content, decoded on-device (no server round-trip).
• Queue, shuffle, repeat, recently-played, and a floating mini-player that follows you across the app.

👥 Social & Real-Time

• Jam Rooms — listen together in real time; playback stays in sync across participants.
• Live friend activity — see what people are playing right now via presence + now-playing broadcasts.
• Direct messages & group chats — reactions, mentions, swipe-to-reply, typing/read state, and an inbox with request gating.
• Follow graph & friend requests — relationships, followers/following, and an activity center for notifications.
• Push notifications for messages, follows, likes, comments, and Jam invites.

🎵 Creating & Curating

• Upload audio & video with large-file streaming uploads.
• Albums & Playlists — collaborative, with per-item visibility, emoji / gradient cover art, and a collaborator picker.
• Stories — share ephemeral, clipped highlights.
• Reposts with custom clip windows.
• Comments, likes, and reporting with moderation hooks.

🔐 Accounts

• Email/Password + Google Sign-In, with a permanent-username onboarding flow.
• Profiles with avatars, bios, edit-profile, and rich profile grids.

---

🏗️ Engineering Highlights

The interesting parts aren’t the feature list — they’re the hard problems behind it. A few worth calling out:

• Single-engine audio architecture. Exactly one media-session owner powers playback for the entire app. An earlier two-engine design churned the OS MediaSession on every audio↔video boundary, producing duplicate “carousel” notifications and dropped skip events — consolidating to one engine eliminated an entire class of bugs.
• Native background auto-advance. Because Fabric defers JS-driven view commands while the app is backgrounded, track advancement and clip-end looping are handled natively (Android foreground service) so the lock screen stays correct even when JS is asleep.
• Patched react-native-video. Lock-screen clip-relative timelines required patching the native player and threading new props through the codegen spec — a precise, version-pinned native patch captured in patches/.
• On-device, fail-safe audio analysis. The loudness/frequency envelope behind the visualizer is computed with the phone’s hardware decoder via a one-shot decode that never touches the playback engine. It’s strictly audio-only (decoding a video’s bytes would OOM the process) and degrades gracefully to a decorative wave on any failure.
• Real-time backend on Supabase. Postgres with row-level security, realtime publications for chat/presence/Jam, RPCs for atomic operations, and storage buckets for media — all schema-managed through 30+ versioned migrations.

A deep, battle-tested architecture doc lives in CLAUDE.md, capturing the “why” behind every hard-won decision.

---

🧰 Tech Stack

Layer	Technology
Mobile	React Native 0.85.3 · New Architecture (Fabric) · TypeScript · no Expo
Navigation	React Navigation v7 (native-stack)
State / Realtime	React Context + Supabase Realtime
Backend & Auth	Supabase (PostgreSQL · Auth · Realtime · Storage)
Media	Patched react-native-video · react-native-audio-api (on-device decode) · react-native-svg
Animation / Gesture	Reanimated 4 · Worklets · Gesture Handler
Auth providers	Email/Password · Google OAuth

---

📂 Project Structure

livil/
├── src/
│   ├── screens/          # 28 screens — auth, feed, player, chat, jam, albums, profile…
│   ├── components/       # 40+ reusable UI + the single playback engine
│   ├── services/         # 21 backend service modules (posts, messages, jam, uploads…)
│   ├── contexts/         # playback, jam, relationships, stories, toast…
│   ├── navigation/       # native-stack navigators + session guard
│   └── theme/            # dark design system
├── supabase/migrations/  # 30+ versioned schema migrations
├── patches/              # native react-native-video patch (lock-screen controls)
└── android/ · ios/       # native projects

---

🎨 Design System

A single, consistent dark aesthetic — no light mode.

Token	Value
Background	#0A0A0F
Surface	#12121A
Primary accent	#8B3DFF (purple)
Secondary accent	#00BFFF (neon blue)
Success / Danger	#00C853 / #FF4444

Outlined CTAs with a purple gradient glow border (never a solid fill), animated focus borders, and a floating bottom tab bar.

---

🚀 Getting Started

Requires the React Native environment (Node 20, Java 17, Android SDK / Xcode).

# 1. Install dependencies
npm install

# 2. Start Metro
npm start

# 3. Run on a device/emulator (in a second terminal)
npm run android
# or
npm run ios     # requires: bundle install && bundle exec pod install

Supabase keys are configured in lib/supabase.ts.

Release build (Android)

# Bump versionCode + versionName in android/app/build.gradle first
cd android && ./gradlew bundleRelease
# → android/app/build/outputs/bundle/release/app-release.aab

---

🗺️ Roadmap

• iOS lock-screen clip parity — clip-relative timeline + native auto-advance (Android-complete; iOS in progress).
• Cloudflare R2 media storage migration.
• Synced waveform for video posts (currently audio-only).
• Web uploader for large 4K media.

---

📦 Status

Livil Music is live in production — free on all three platforms:

Platform	Where
📱 iPhone	App Store — "Livil Music"
🤖 Android	Google Play — package com.livil
🌐 Web	livil-music.com/studio — web app + creator dashboard

Still in active development, with new releases shipping to both stores.

Built with React Native · TypeScript · Supabase