Cofi

cofi.sh — Stream YouTube music with a matching GIF background.
Ad‑free, responsive, and visually focused.

Features

• Play music from YouTube via API (ad‑free experience in the app).
• Show a thematically relevant GIF during playback.
• Mobile‑first layout and simple controls.
• Minimal, distraction‑free UI.

Architecture

• Frontend: Browser UI for playback and GIF display.
• Backend/API: Proxies YouTube and a GIF provider; returns stream + GIF metadata.
• Data layer (optional): Users, playlists, videos, GIFs, and join tables when persistence is needed.

Tech Stack

Layer	Technologies (example)
Frontend	HTML, CSS, JavaScript
API	Node.js / Express (or your equivalent)
External	YouTube Data API, GIF service (e.g., Giphy)

Quick start

git clone https://github.com/gerrgg/cofi.git
cd cofi
npm install
npm start

Open http://localhost:3000

Configuration

Create a .env file (adjust names to your implementation):

YOUTUBE_API_KEY=your_youtube_key
GIF_API_KEY=your_gif_service_key
API_BASE_URL=http://localhost:3000
NODE_ENV=development
PORT=3000

API (examples)

Your API may differ; these routes are illustrative.

Method	Path	Description
GET	/api/play?key=YOUTUBE_ID	Returns stream URL and matching GIF meta
GET	/api/gif?theme=lofi	Returns a themed GIF URL
GET	/api/search?q=query	Optional search endpoint

Data model (optional persistence)

• users(id, name, email, activation_hash, is_active, created_at)
• playlists(id, user_id, title, created_at)
• videos(id, key UNIQUE, title, thumbnail, created_at)
• gifs(id, url UNIQUE)
• playlist_videos(playlist_id, video_id, gif_id NULL, position, added_at, PRIMARY KEY(playlist_id, video_id))

Notes:

• Videos are deduped by key (YouTube id).
• GIFs are deduped by url.
• A video can have a playlist‑specific GIF via playlist_videos.gif_id.
• position supports ordering inside a playlist.

Deployment

• Serve frontend and API behind HTTPS.
• Use object storage + CDN if you self‑host GIFs.
• Monitor API quotas (YouTube, GIF provider).
• Add caching for repeated lookups.

Costs

Storage is inexpensive; egress/bandwidth dominates. Plan CDN usage based on expected GIF sizes and traffic.

Contributing

1. Fork the repo
2. Create a feature branch
3. Commit with clear messages
4. Open a Pull Request

License

MIT