{"id":48411448,"url":"https://github.com/cwklurks/hook-gen","last_synced_at":"2026-04-06T06:07:41.965Z","repository":{"id":317596317,"uuid":"1066480267","full_name":"cwklurks/hook-gen","owner":"cwklurks","description":"Turn your drum loops into melodies. Upload a beat, and this tool generates matching hooks that lock to the groove and key.","archived":false,"fork":false,"pushed_at":"2026-03-21T07:30:14.000Z","size":50784,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T23:32:56.549Z","etag":null,"topics":["algorit","docker","fast-api","hmic-com","librosa","music-generation","music-theory","nextjs","python","react","typescript"],"latest_commit_sha":null,"homepage":"https://hookgen.vercel.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cwklurks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-09-29T14:40:13.000Z","updated_at":"2026-03-21T07:30:18.000Z","dependencies_parsed_at":"2025-10-01T22:20:08.916Z","dependency_job_id":null,"html_url":"https://github.com/cwklurks/hook-gen","commit_stats":null,"previous_names":["cwklurks/hook-gen"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cwklurks/hook-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwklurks%2Fhook-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwklurks%2Fhook-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwklurks%2Fhook-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwklurks%2Fhook-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cwklurks","download_url":"https://codeload.github.com/cwklurks/hook-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cwklurks%2Fhook-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31461563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"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":["algorit","docker","fast-api","hmic-com","librosa","music-generation","music-theory","nextjs","python","react","typescript"],"created_at":"2026-04-06T06:07:40.846Z","updated_at":"2026-04-06T06:07:41.960Z","avatar_url":"https://github.com/cwklurks.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n# Hook-Gen\n\n**Turn any drum loop into five melodic hooks that lock to the groove.**\n\n[![CI](https://github.com/cwklurks/hook-gen/actions/workflows/test.yml/badge.svg)](https://github.com/cwklurks/hook-gen/actions/workflows/test.yml)\n\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-3178c6.svg)](https://www.typescriptlang.org/)\n\n[View Demo]([(https://hookgen.vercel.app/)]) • [Report Bug](https://github.com/cwklurks/hook-gen/issues) • [Request Feature](https://github.com/cwklurks/hook-gen/issues)\n\n\u003c/div\u003e\n\n---\n\n## 📖 About\n\n**Hook-Gen** is a musical ideation engine designed for beatmakers and developers. Unlike \"black box\" generative AI that relies on massive pre-trained checkpoints, Hook-Gen uses **deterministic, explainable algorithms** to analyze audio and generate musical content.\n\nDrop in a rhythmic loop (WAV/MP3), and the system analyzes the **onset histogram** (groove) and **chroma features** (key/scale). It then procedurally generates monophonic MIDI/Audio hooks that mathematically lock to your loop's specific feel.\n\n### Key Features\n\n* **🎛️ Groove-Aware Sampling:** Rhythm generation is driven by the uploaded loop's onset density.\n\n* **🎯 Contextual Pitching:** Automatic scale detection using `librosa` chroma templates.\n\n* **🎹 In-Browser Synthesis:** Instant preview using Tone.js on the frontend.\n\n* **📦 Production Ready:** Downloads organized zip bundles with WAV/MIDI stems.\n\n* **⚡ Lightweight:** Runs entirely on CPU; no GPU required.\n\n---\n\n## 📸 Demo\n\n![Application Demo](docs/demo.gif)\n\n---\n\n## 🛠 Tech Stack\n\nThis project uses a modern decoupled architecture:\n\n### **Frontend (The Interface)**\n\n* **Framework:** [Next.js 14](https://nextjs.org/) (React Server Components)\n\n* **Styling:** Tailwind CSS + Framer Motion\n\n* **Audio:** [Wavesurfer.js](https://wavesurfer-js.org/) (Visualization) + [Tone.js](https://tonejs.github.io/) (Playback)\n\n### **Backend (The Brain)**\n\n* **API:** [FastAPI](https://fastapi.tiangolo.com/) (Python)\n\n* **DSP:** [Librosa](https://librosa.org/) (Audio Analysis) + NumPy\n\n* **MIDI:** Mido / PrettyMIDI\n\n---\n\n## 🚀 Quick Start\n\nThe easiest way to run Hook-Gen locally is via Docker.\n\n### Prerequisites\n\n* Docker \u0026 Docker Compose\n\n### Installation\n\n1.  **Clone the repo**\n\n    ```bash\n\n    git clone https://github.com/cwklurks/hook-gen.git\n\n    cd hook-gen\n\n    ```\n\n2.  **Start the services**\n\n    ```bash\n\n    docker-compose up --build\n\n    ```\n\n3.  **Access the app**\n\n    * Frontend: `http://localhost:3000`\n\n    * Backend API Docs: `http://localhost:8000/docs`\n\n---\n\n## 🧠 How It Works (The Algorithm)\n\nHook-Gen operates on an \"Explainable AI\" philosophy. Here is the pipeline:\n\n1.  **Signal Conditioning:** The audio is loaded into `Librosa`, converted to mono, and trimmed.\n\n2.  **Rhythm Extraction:**\n\n    * We calculate an onset envelope to estimate BPM.\n\n    * A 16-step **Groove Histogram** is built by mapping detected onsets to a 16th-note grid.\n\n3.  **Scale Detection:**\n\n    * We generate a Chroma Constant-Q Transform (CQT).\n\n    * This vector is compared against 24 template scales (Major/Minor for all roots) to determine the musical key confidence.\n\n4.  **Generation:**\n\n    * **Rhythm:** We sample from the Groove Histogram (weighted by the \"Groove Push\" slider).\n\n    * **Pitch:** We perform a constrained random walk within the detected scale, ensuring the phrase resolves to the tonic (root note).\n\n---\n\n## 📂 Project Structure\n\n```bash\n\nhook-gen/\n\n├── backend/                # Python FastAPI Server\n\n│   ├── app/\n\n│   │   ├── motif.py        # Pitch generation logic\n\n│   │   ├── rhythm.py       # Tempo \u0026 Groove analysis\n\n│   │   └── export.py       # MIDI/WAV file creation\n\n│   └── examples/           # Included audio loops for testing\n\n│\n\n├── frontend/               # Next.js Application\n\n│   ├── src/components/     # React UI Components (PianoRoll, Waveform)\n\n│   └── public/             # Static assets\n\n│\n\n└── hook-aid/               # Legacy Streamlit Prototype (Reference)\n\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.\n\n1. Fork the Project\n\n2. Create your Feature Branch (git checkout -b feature/AmazingFeature)\n\n3. Commit your Changes (git commit -m 'Add some AmazingFeature')\n\n4. Push to the Branch (git push origin feature/AmazingFeature)\n\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nDistributed under the MIT License. See LICENSE for more information.\n\n---\n\n## 🔮 Roadmap\n\n- [ ] MIDI Export UI: Allow downloading .mid files directly from the player.\n\n- [ ] Polyphony: Add chord generation based on implied harmony.\n\n- [ ] Style Presets: Add \"Trap\", \"House\", and \"Lofi\" bias settings to the rhythm sampler.\n\n---\n\n\u003cdiv align=\"center\"\u003e \u003csmall\u003eBuilt with 🎵 by \u003ca href=\"https://github.com/cwklurks\"\u003ecwklurks\u003c/a\u003e\u003c/small\u003e \u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwklurks%2Fhook-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcwklurks%2Fhook-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcwklurks%2Fhook-gen/lists"}