{"id":50569643,"url":"https://github.com/rolling-codes/juice-wrld-finder","last_synced_at":"2026-06-04T17:30:18.889Z","repository":{"id":362121998,"uuid":"1257486438","full_name":"rolling-codes/juice-wrld-finder","owner":"rolling-codes","description":"Discord bot and web app for searching Juice WRLD song metadata. Integrates with the Juice WRLD community API for download links. Metadata discovery and organization platform only - use responsibly.","archived":false,"fork":false,"pushed_at":"2026-06-02T19:29:13.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-02T20:16:00.977Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rolling-codes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T18:15:15.000Z","updated_at":"2026-06-02T19:29:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rolling-codes/juice-wrld-finder","commit_stats":null,"previous_names":["rolling-codes/juice-wrld-finder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rolling-codes/juice-wrld-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolling-codes%2Fjuice-wrld-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolling-codes%2Fjuice-wrld-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolling-codes%2Fjuice-wrld-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolling-codes%2Fjuice-wrld-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rolling-codes","download_url":"https://codeload.github.com/rolling-codes/juice-wrld-finder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rolling-codes%2Fjuice-wrld-finder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33916319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T17:30:18.142Z","updated_at":"2026-06-04T17:30:18.872Z","avatar_url":"https://github.com/rolling-codes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Juice WRLD Metadata Finder\n\nA Discord bot, web app, and FastAPI backend for searching and organizing Juice WRLD song metadata. This project indexes released and unreleased songs, eras, producers, and related metadata, with a public-facing gallery and admin panel for link management.\n\n**This project is a metadata discovery platform, not a file distribution service.**\n\n---\n\n## ⚠️ Disclaimer\n\nThis project is fan-made and not affiliated with Juice WRLD, his estate, or any label. Use responsibly and respectfully.\n\n**This project includes a connection to the Juice WRLD community API.**\n\n**rolling-codes is not responsible for:**\n- Any software downloads or file distribution via this tool or connected APIs\n- Any copyright infringement or unauthorized distribution\n- Any leaks or unauthorized sharing of copyrighted material\n- Any misuse of the Juice WRLD community API\n\nUsers bear full responsibility for complying with copyright laws and the terms of service of any APIs used. The Juice WRLD community API integration is provided as-is for metadata purposes only.\n\nFor official Juice WRLD music, visit [streaming platforms](https://open.spotify.com/artist/4MCBfE4596Uoi2O4DtmHO1).\n\n---\n\n## Download Functionality\n\nThe app provides direct download access to songs from public sources:\n\n- **Web Gallery:** Click the download button (↓) next to any link on the song detail page\n- **API Endpoint:** `GET /downloads/{song_id}` redirects to the first available PUBLIC link\n- **Specific Link:** `GET /downloads/{song_id}?link_id={link_id}` downloads a specific source\n\n**Supported Sources:**\n- Juice WRLD API (community metadata)\n- MEGA folders (if configured)\n- Official streaming links (where available)\n\nDownloads are restricted to PUBLIC visibility links. Admin-only links require authentication.\n\n---\n\n## Release Versions and References\n\nSongs can now include child records for alternate release versions and metadata references:\n\n- **Versions** group released, demo, session edit, base, and alternate versions under one song.\n- **Base version** marks the earliest known or source version for a song.\n- **References** cite metadata sources such as Juice WRLD API, Vault, Juicehub, MusicBrainz, Musicfetch, SonoVault, or manual notes.\n- References are metadata only. They are never treated as download links unless an admin separately creates a PUBLIC download link.\n\nPublic endpoints:\n\n```http\nGET /songs/{song_id}/versions\nGET /songs/{song_id}/references\n```\n\nCSV import supports optional pipe-delimited columns:\n\n- `versions`: `title:base|Demo:10:notes`\n- `references`: `source_name,source_url,source_type,description`\n- `download_links`: `label,url,link_type,visibility`\n\n---\n\n## Getting Started with Data\n\nTo populate the database with song metadata:\n\n### Option A: Load From Juice WRLD API (Recommended)\n```bash\npython scripts/sync_juiceboard_api.py\n```\n\n### Option B: Use Sample CSV\n```bash\npython scripts/import_csv.py songs.csv\n```\n\n### Option C: Manual Entry via Admin Panel\nOnce the app is running, use the admin interface to add songs individually.\n\n---\n\n## Version History\n\n### V1 (Current)\n\n**What it is:**\n- Fully-functional FastAPI metadata backend with 12 database models and 18+ API endpoints\n- Public-facing React web app (song gallery, search, detail pages, downloads)\n- Discord bot with search, era browsing, random song selection, and admin commands\n- Download functionality via Juice WRLD API and MEGA folders\n- SQLite database with comprehensive music metadata schema\n- CSV/JSON bulk import tooling for easy data seeding\n\n**Features:**\n- Core metadata models (songs, aliases, eras, producers, sessions, lyrics, cover art, media references)\n- Full-text + fuzzy search with RapidFuzz\n- MEGA folder integration (indexing and download links)\n- Juice WRLD API integration (metadata + download links)\n- Public web gallery with song browsing and search\n- Song detail pages with metadata and download options\n- Discord bot with metadata commands + admin tools\n- Download API endpoint (`GET /downloads/{song_id}`)\n- Link visibility control (PUBLIC/BOT/ADMIN)\n- 90%+ test coverage with pytest\n- Docker Compose setup (SQLite, Redis, bot, API)\n- GitHub Actions CI pipeline (ruff, mypy, pytest)\n- Complete documentation and deployment guides\n\n**Out of Scope (V1):**\n- Admin panel (link management UI) — coming in V2\n- User authentication (JWT admin login) — coming in V2\n- PostgreSQL migration (phase 2 infrastructure)\n\n**Deployment:** Local development or Docker Compose. Choose web-only, bot-only, or full stack deployment.\n\n---\n\n### V2 (Planned)\n\n- React SPA public gallery + admin panel\n- JWT auth for admin operations\n- API key auth for bot HTTP requests\n- Download link visibility model (public/bot/admin)\n- New routes: `/auth/login`, `/links` (CRUD), `/bot/*`\n- Security hardening: protected admin routes, CORS config\n- OAuth2 / OAuth2PasswordBearer flow\n- Better error handling and validation\n\n---\n\n## Features\n\n- 🔍 **Fast Search** — Full-text + fuzzy search across song titles, aliases, and producers\n- 🔎 **Advanced Filtering** — Discover songs by era, release status, producer, and recording date\n- 🤖 **Discord Bot** — Native Discord slash commands for instant metadata lookups\n- 🌐 **REST API** — FastAPI backend for programmatic access\n- 🎵 **Comprehensive Metadata** — Songs, eras, producers, sessions, lyrics, cover art\n- 📥 **Download Integration** — Direct links to Juice WRLD API and MEGA folders\n- 🔐 **Safe By Default** — Controlled download link exposure via environment flags\n- 📊 **Admin Tools** — CSV/JSON import, MEGA folder indexing, manual edits\n- 🧪 **90%+ Test Coverage** — Production-ready test suite\n\n## Installation Guides\n\nChoose your deployment scenario below. All require Python 3.11+ and a cloned repository.\n\nGitHub Releases provide three ready-to-unpack packages:\n\n- `juice-wrld-finder-desktop-app-view.zip` for the local desktop/web app experience.\n- `juice-wrld-finder-discord-bot.zip` for the Discord bot plus backend.\n- `juice-wrld-finder-discord-bot-plus-web.zip` for the complete Discord bot and web deployment.\n\nRelease packages include `.env.example` only. Local databases, credentials, node modules, virtual environments, generated coverage, and direct private folder links are excluded.\n\n### Setup: Clone and Install Dependencies\n\n```bash\ngit clone https://github.com/rolling-codes/juice-wrld-finder.git\ncd juice-wrld-finder\npip install -r requirements.txt\n```\n\n---\n\n### Option 1: Web App Only (No Discord)\n\nUse this if you want the public gallery + admin panel without the Discord bot.\n\n**Configure `.env`:**\n```env\nSECRET_KEY=your_secret_key_here\nCORS_ORIGINS=[\"http://localhost:5173\"]\nDATABASE_URL=sqlite:///./juice_wrld.db\n```\n\n**Run:**\n```bash\n# Terminal 1: Backend API (port 8000)\npython -c \"from app.db import Base, engine; Base.metadata.create_all(bind=engine)\"\nuvicorn app.main:app --reload\n\n# Terminal 2: Frontend (port 5173)\ncd web\nnpm install\nnpm run dev\n```\n\n**Access:**\n- Web app: http://localhost:5173\n- API docs: http://localhost:8000/docs\n\n---\n\n### Option 2: Discord Bot Only (No Web App)\n\nUse this if you want just the Discord bot with backend metadata, no web interface.\n\n**Configure `.env`:**\n```env\nDISCORD_TOKEN=your_bot_token\nDISCORD_GUILD_ID=your_guild_id\nADMIN_ROLE_ID=your_admin_role_id\nSECRET_KEY=your_secret_key_here\nDATABASE_URL=sqlite:///./juice_wrld.db\n# Optional: for download link visibility\nEXPOSE_API_DOWNLOAD_LINKS=true\nEXPOSE_MEGA_LINKS=false\n```\n\n**Run:**\n```bash\n# Terminal 1: Backend API (port 8000)\npython -c \"from app.db import Base, engine; Base.metadata.create_all(bind=engine)\"\nuvicorn app.main:app --reload\n\n# Terminal 2: Discord Bot\npython -m app.bot.client\n```\n\n**Use in Discord:**\n- `/jw search \u003cquery\u003e` — Search songs\n- `/jw song \u003cid\u003e` — Get song details\n- `/jw era \u003cera_name\u003e` — Browse by era\n- `/jw random` — Random song\n\n---\n\n### Option 3: Full Stack (Web App + Discord Bot)\n\nUse this for complete functionality: web gallery, admin panel, and Discord integration.\n\n**Configure `.env`:**\n```env\n# Discord\nDISCORD_TOKEN=your_bot_token\nDISCORD_GUILD_ID=your_guild_id\nADMIN_ROLE_ID=your_admin_role_id\n\n# Web App\nSECRET_KEY=your_secret_key_here\nCORS_ORIGINS=[\"http://localhost:5173\"]\nDATABASE_URL=sqlite:///./juice_wrld.db\n\n# Optional Downloads\nEXPOSE_API_DOWNLOAD_LINKS=true\nEXPOSE_MEGA_LINKS=false\n```\n\n**Run:**\n```bash\n# Terminal 1: Backend API (port 8000)\npython -c \"from app.db import Base, engine; Base.metadata.create_all(bind=engine)\"\nuvicorn app.main:app --reload\n\n# Terminal 2: Discord Bot\npython -m app.bot.client\n\n# Terminal 3: Frontend (port 5173)\ncd web\nnpm install\nnpm run dev\n```\n\n**Access:**\n- Web app: http://localhost:5173\n- Discord commands: `/jw ...`\n- API docs: http://localhost:8000/docs\n\n---\n\n### Import Initial Data\n\nPrepare a CSV file with columns: `title`, `era`, `release_status`, `download_status`, `official_url`, `api_download_url`, `notes`, `aliases`, `producers`\n\n```bash\npython scripts/import_csv.py songs.csv\n```\n\n## Commands\n\n### User Commands\n\n- `/jw search \u003cquery\u003e` — Search songs by title, alias, or keyword\n- `/jw song \u003cid\u003e` — Get full metadata for a song\n- `/jw era \u003cera_name\u003e` — List songs from an era\n- `/jw random` — Get a random song\n- `/jw lyrics \u003cphrase\u003e` — Search indexed lyric snippets\n\n### Admin Commands (requires `ADMIN_ROLE_ID`)\n\n- `/jw admin add-song \u003ctitle\u003e` — Add a new song\n- `/jw admin edit-song \u003cid\u003e \u003cupdates\u003e` — Edit song metadata\n- `/jw admin remove-song \u003cid\u003e` — Delete a song\n- `/jw admin reindex` — Reindex MEGA folders\n\n## API Endpoints\n\n```\nGET  /health                           # Health check\nGET  /songs?era_id=1\u0026release_status=released  # List songs with filters\nGET  /songs/{id}                       # Get song details\nGET  /songs/{id}/versions              # Get release/demo/session versions\nGET  /songs/{id}/references            # Get metadata references\nGET  /search?q=\u003cquery\u003e                 # Search songs\nGET  /search/lyrics?q=\u003cphrase\u003e         # Search lyrics\nGET  /eras                             # List all eras\nGET  /eras/{id}                        # Get era details\nGET  /eras/{id}/songs                  # Get songs from era\nGET  /producers                        # List producers\nGET  /downloads/{song_id}              # Download a song (redirects to source)\n\nPOST   /admin/songs                    # Create song\nPATCH  /admin/songs/{id}               # Update song\nDELETE /admin/songs/{id}               # Delete song\n```\n\n**Song Filter Parameters:**\n- `era_id` — Filter by era (e.g., `?era_id=1`)\n- `release_status` — Filter by status: `released`, `unreleased`, `unknown`\n- `skip` — Pagination offset (default: 0)\n- `limit` — Results limit (default: 100)\n\n## Configuration\n\n### Feature Flags\n\n```env\nEXPOSE_API_DOWNLOAD_LINKS=false   # Show Juice WRLD API download links\nEXPOSE_MEGA_LINKS=false           # Show MEGA folder download links\n```\n\n### MEGA Folders\n\nConfigure these in `.env` to enable MEGA indexing:\n\n```env\nMEGA_MAIN_COMP=\nMEGA_ERA_COMP=\nMEGA_COVER_ART_COMP=\nMEGA_MEDIA_COMP=\nMEGA_SESSION_EDITS_COMP=\n```\n\n## Data Sources\n\nThis project uses publicly available metadata from:\n\n1. **Official Releases** — Spotify, Apple Music, YouTube\n2. **Juice WRLD API** — https://juicewrldapi.com (Juice WRLD community API)\n3. **User-Submitted Data** — Via CSV/JSON import\n4. **MEGA Folder References** — Filename indexing only (no downloads)\n\nSee [docs/REFERENCE_LINKS.md](docs/REFERENCE_LINKS.md) and [docs/API_SOURCES.md](docs/API_SOURCES.md) for details.\n\n## Features\n\n✅ **Direct External Links** — Links to Juice WRLD API and MEGA (no proxying)\n✅ **Controlled link exposure** — Download URLs only shown if explicitly enabled\n✅ **URL redaction** — Private file-hosting links redacted from bot responses\n✅ **Admin-only operations** — Sensitive commands require role verification\n✅ **Audit logging** — All admin actions logged\n\n## Testing\n\nRun the full test suite:\n\n```bash\npytest --cov=app --cov-report=term-missing\n```\n\nLinting and type checking:\n\n```bash\nruff check .\nmypy app\n```\n\nSee [docs/TESTING.md](docs/TESTING.md) for detailed testing guide.\n\n## Deployment\n\n### Docker Compose (Local)\n\n```bash\ndocker-compose up --build\n```\n\nThis starts:\n- API on port 8000\n- Bot (connects to Discord)\n- Redis on port 6379\n- SQLite database\n\n### Production (VPS)\n\nFor Railway, Fly.io, or similar:\n\n1. Set environment variables\n2. Build Docker image\n3. Deploy with persistent database volume\n4. Use PostgreSQL + Redis instead of SQLite\n\nSee `docker-compose.yml` for the services definition.\n\n## Project Structure\n\n```\njuice-wrld-finder/\n├── app/\n│   ├── api/          # FastAPI routes\n│   ├── bot/          # Discord bot + cogs\n│   ├── core/         # Config, security\n│   ├── db/           # SQLAlchemy setup\n│   ├── models/       # Database models\n│   ├── repositories/ # Data access layer\n│   ├── services/     # Business logic\n│   └── integrations/ # External APIs (Juice WRLD, MEGA)\n├── scripts/          # CSV importer, utilities\n├── tests/            # Pytest test suite\n├── docs/             # Documentation\n├── Dockerfile        # Container image\n└── docker-compose.yml\n```\n\n## Development\n\nClone, install, and run locally:\n\n```bash\ngit clone \u003crepo\u003e\ncd juice-wrld-finder\npip install -r requirements.txt\n\n# Terminal 1: API\nuvicorn app.main:app --reload\n\n# Terminal 2: Bot\npython -m app.bot.client\n```\n\nChanges auto-reload in both processes.\n\n## API Integration Note\n\nThis project integrates with the **Juice WRLD API** ([https://juicewrldapi.com/](https://juicewrldapi.com/)) which may provide download links for songs. This tool is designed for **metadata discovery and organization only**. \n\n**Disclaimer:** This project includes a reference to the Juice WRLD API that *can* be used to download songs, but **the rolling-codes team does not advise or endorse any software downloads or distribution**. Users are solely responsible for complying with copyright laws and the terms of service of any APIs used. **rolling-codes is not responsible for any downloads, leaks, or unauthorized distribution of copyrighted material.** Only download songs you have permission to download. Support the artist by using official streaming platforms when available.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new code\n4. Ensure 90%+ coverage\n5. Submit a pull request\n\nAll tests and linting must pass (see GitHub Actions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolling-codes%2Fjuice-wrld-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frolling-codes%2Fjuice-wrld-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frolling-codes%2Fjuice-wrld-finder/lists"}