tabatago/SUPABASE_MUSIC_SETUP.md

Supabase Music Storage Setup

This guide walks you through setting up the Supabase Storage bucket for music tracks in TabataFit.

Overview

TabataFit loads background music from Supabase Storage based on workout musicVibe values. The music service organizes tracks by vibe folders.

Step 1: Create the Storage Bucket

1. Go to your Supabase Dashboard → Storage
2. Click New bucket
3. Name: music
4. Enable Public access (tracks are streamed to authenticated users)
5. Click Create bucket

Step 2: Set Up Folder Structure

Create folders for each music vibe:

music/
├── electronic/
├── hip-hop/
├── pop/
├── rock/
└── chill/

Via Dashboard:

1. Open the music bucket
2. Click New folder for each vibe
3. Name folders exactly as the MusicVibe type values

Via SQL (optional):

-- Storage folders are virtual in Supabase
-- Just upload files with path prefixes like "electronic/track.mp3"

Step 3: Upload Music Tracks

Supported Formats

• MP3 (recommended)
• M4A (AAC)
• OGG (if needed)

File Naming Convention

Name files with artist and title for best results:

Artist Name - Track Title.mp3

Examples:

Neon Dreams - Energy Pulse.mp3
Urban Flow - Street Heat.mp3
The Popstars - Summer Energy.mp3

Upload via Dashboard:

1. Open a vibe folder (e.g., electronic/)
2. Click Upload files
3. Select your audio files
4. Ensure the path shows music/electronic/

Upload via CLI:

# Install Supabase CLI if not already installed
npm install -g supabase

# Login
supabase login

# Link your project
supabase link --project-ref your-project-ref

# Upload tracks
supabase storage upload music/electronic/ "path/to/your/tracks/*.mp3"

Step 4: Configure Storage Policies

RLS Policy for Authenticated Users

Go to Supabase Dashboard → Storage → Policies → music bucket

Add these policies:

1. Select Policy (Read Access)

CREATE POLICY "Allow authenticated users to read music"
ON storage.objects FOR SELECT
TO authenticated
USING (bucket_id = 'music');

2. Insert Policy (Admin Upload Only)

CREATE POLICY "Allow admin uploads"
ON storage.objects FOR INSERT
TO authenticated
WITH CHECK (
  bucket_id = 'music' 
  AND (auth.jwt() ->> 'role') = 'admin'
);

Via Dashboard UI:

1. Go to Storage → Policies
2. Under music bucket, click New policy
3. Select For SELECT (get)
4. Allowed operation: Authenticated
5. Policy definition: true (or custom check)

Step 5: Test the Setup

1. Start your Expo app: npx expo start
2. Start a workout with music enabled
3. Check console logs for:

   [Music] Loaded X tracks for vibe: electronic
   

Troubleshooting

No tracks loading:

• Check Supabase credentials in .env
• Verify folder names match MusicVibe type exactly
• Check Storage RLS policies allow read access

Tracks not playing:

• Ensure files are accessible (try signed URL in browser)
• Check audio format is supported by expo-av
• Verify CORS settings in Supabase

CORS errors: Add to Supabase Dashboard → Settings → API → CORS:

app://*
http://localhost:8081

Step 6: Environment Variables

Ensure your .env file has:

EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Music Vibes Reference

The app supports these vibe categories:

Vibe	Description	Typical BPM
electronic	EDM, House, Techno	128-140
hip-hop	Rap, Trap, Beats	85-110
pop	Pop hits, Dance-pop	100-130
rock	Rock, Alternative	120-160
chill	Lo-fi, Ambient, Downtempo	60-90

Best Practices

1. Track Duration: 3-5 minutes ideal for Tabata workouts
2. File Size: Keep under 10MB for faster loading
3. Bitrate: 128-192kbps MP3 for good quality/size balance
4. Loudness: Normalize tracks to similar levels (-14 LUFS)
5. Metadata: Include ID3 tags for artist/title info

Alternative: Local Development

If Supabase is not configured, the app uses mock tracks automatically. To force mock data, temporarily set invalid Supabase credentials.

Next Steps

• Upload initial track library (5-10 tracks per vibe)
• Test on physical device
• Consider CDN for production scale
• Implement track favoriting/personal playlists