Convention: What is the workflow to add a new song to GoGrab Pulse?

Documentation for Sessions

📏 Convention: What is the workflow to add a new song to GoGrab Pulse?

Date: 2026-02-12
Time: 04:20:44 UTC
Session: gspace1-108.8
Agent: backend
Confidence: 97%
Status: ✅ Documented

📋 Decision Context

Question:

What is the workflow to add a new song to GoGrab Pulse?

Task: GoGrab Pulse - How to add new songs

🎯 Decision Made

Chosen:

Three-step process: upload MP3 to R2, update songs.json, redeploy Pages

Options Considered:

  1. Manual R2 upload + JSON edit
  2. Automated script
  3. Backend API only
  4. Direct FTP upload

💭 Reasoning

Adding a new song requires 3 steps: (1) Upload MP3 to R2: npx wrangler r2 object put gograb-pulse-music/songs/{filename}.mp3 --file=/path/to/file.mp3 --remote --content-type=audio/mpeg. The --remote flag is mandatory. (2) Edit deploy/gograb-pulse/music/songs.json - add a new entry with: title, artist, filename (just the .mp3 name), lang (en/es), genre (optional: latin/worship/inspirational), cover (optional: filename in covers/ prefix on R2). The r2BaseUrl at the top of songs.json tells the player where to stream from. (3) Redeploy: npx wrangler pages deploy deploy/gograb-pulse --project-name=gograb-pulse --branch=main. For cover art: upload image to R2 under covers/ prefix: npx wrangler r2 object put gograb-pulse-music/covers/{image}.jpg --file=/path/to/image.jpg --remote --content-type=image/jpeg, then set the cover field in songs.json. The sync script (tools/scripts/sync-pulse-music.sh) can automate bulk uploads from a source directory including the iCloud Music folder. Songs without a cover field get an auto-generated gradient based on the song title. The backend NestJS PulseModule (apis/backend-api/src/app/pulse/) also stores song metadata in MongoDB for future dynamic playlist management, but the player currently reads from the static songs.json.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation