FurhanShaikh/musicgen-forge

A next-generation companion framework for fine-tuning generative audio models on your own private sound world.

Welcome to HarmonicForge, a research-grade training environment built for composers, sound designers, indie game studios, and AI tinkerers who want to teach a music-generation model their style — not someone else's. Where the original musicgen_trainer gave you a modest workshop bench, HarmonicForge hands you an entire conservatory: a modular, extensible, endlessly tweakable laboratory for shaping generative music into something that sounds unmistakably like you.

Think of it as a gardener's toolkit for melody. You bring the seeds (your audio dataset), we bring the greenhouse, the irrigation system, and a dashboard telling you exactly how each sprout is doing. No guesswork. No black boxes you can't peek inside. Just transparent, reproducible, thoughtfully engineered training.

• Why HarmonicForge Exists
• Project Vision
• Feature Highlights
• Architecture Overview
• Supported Workflows
• Responsive Interface
• Multilingual Support
• Twenty-Four Seven Assistance
• Repository Layout
• Configuration Model
• Dataset Preparation Philosophy
• Training Pipeline
• Evaluation & Listening Sessions
• Export & Interoperability
• Performance & Hardware Notes
• Roadmap for 2026
• Frequently Asked Questions
• Contributing
• Code of Conduct
• License
• Disclaimer
• Acknowledgements

Generative music models are astonishing. They can hum a plausible tune in nearly any genre on request. But ask one to write in your particular idiom — the way you bend a minor seventh, the swing you apply to hi-hats, the way your basslines breathe — and suddenly it stumbles. Generic training data produces generic output.

HarmonicForge was born from that frustration. It is a training harness that treats your personal catalog as first-class material, not an afterthought. It wraps dataset curation, augmentation, optimization, checkpointing, and live auditioning into one coherent toolchain — so the distance between "I have a folder of my tracks" and "I have a model that sounds like me" shrinks dramatically.

We believe the future of creative AI is personal: models tuned to individuals, small ensembles, and niche communities. HarmonicForge is a small but principled step in that direction.

Three commitments guide every design decision in this repository:

1. Transparency over magic. Every knob, every schedule, every metric is inspectable. If a training run produces an oddity, you should be able to trace why.
2. Composability over monoliths. Each component — data loading, conditioning, optimizer, sampler — plays nicely with the others but can also be swapped without rewriting the world.
3. Craft over convenience. This is a tool for people who care about the sound. That means it favors a slightly steeper learning curve in exchange for meaningful control.

• 🎛️ Modular conditioning system — support for text prompts, melody references, rhythmic grids, and hybrid blends.
• 🧠 Adaptive learning-rate choreography — schedules that react to loss curvature instead of blindly following a calendar.
• 🎚️ Granular augmentation controls — pitch drift, time stretch, spectral tilt, and reverb simulation, each independently toggleable.
• 📊 Live telemetry dashboard — watch loss, gradient norms, and spectral metrics update in real time.
• 🌍 Multilingual support — interface labels and prompt-parser hints available in more than a dozen languages.
• 📱 Responsive UI — monitor long-running jobs from a phone on the train or a triple-monitor workstation at home.
• 🔁 Checkpoint branching — fork a training run from any historical checkpoint and explore divergent paths.
• 🎧 Built-in auditioning — listen to samples at every epoch without leaving the tool.
• 🧩 Plugin surface for custom samplers — bring your own inference logic and register it cleanly.
• 🕛 Twenty-four-seven assistance — around-the-clock support channels for researchers on every timezone.
• 🗂️ Dataset health diagnostics — duplicated tracks, clipping, silence, and unbalanced loudness are all detected automatically.
• 📦 Portable export bundles — package a trained model with metadata for sharing with collaborators.
• 🔐 Local-first operation — your corpus never has to leave your machine unless you decide otherwise.
• 🧾 Audit trail — every run produces a reproducible manifest capturing seeds, hyperparameters, and environment details.

At a high level, HarmonicForge is organized into five collaborating layers:

1. Ingestion Layer — Scans audio directories, builds an index, computes whispered fingerprints for duplicate detection, and emits a normalized manifest.
2. Augmentation Layer — Applies a configurable chain of transforms, each with a probability and intensity envelope.
3. Conditioning Layer — Maps text, melody, and rhythm inputs into a shared embedding space so the model can attend to whichever is present.
4. Optimization Layer — Hosts the training loop, gradient clipping, mixed-precision handling, and checkpoint orchestration.
5. Delivery Layer — Exposes metrics to the dashboard, queues audition samples, and writes export bundles.

These layers communicate through a lightweight event bus, which means you can replace any one of them without disturbing the rest. The result is a system that ages gracefully — even as downstream model architectures evolve.

HarmonicForge anticipates several archetypal journeys:

• Solo Composer Refinement — Train on a personal discography to produce an assistant that drafts ideas in your signature voice.
• Game Studio Audio Farming — Generate hundreds of variations on a theme for adaptive soundtracks, then curate by hand.
• Academic Experimentation — Systematically vary conditioning schemes and measure downstream perceptual scores.
• Community Fine-Tuning Circles — Share export bundles with peers who then continue training from your checkpoint.
• Educational Demonstrations — Show students how generative audio systems learn, with every intermediate stage visible.

Each workflow maps cleanly onto the same underlying pipeline — only the configuration and the size of the corpus differ.

The dashboard is engineered from the ground up to feel natural at any viewport. On a widescreen monitor it presents a multi-column layout with live loss curves, spectral heatmaps, and a running sample player. On a tablet it collapses gracefully into stacked cards. On a phone it becomes a focused, gesture-driven control strip — perfect for checking in on a long overnight run from the comfort of your couch.

Nothing about the interface assumes a desktop. The layout system is fluid, the typography scales, and the controls remain comfortably tappable at even the smallest breakpoints.

HarmonicForge speaks many tongues — literally and figuratively. Interface strings, tooltip copy, error messages, and prompt-parser hints are available in a growing roster of languages. Community translators are warmly welcomed; adding a new locale is a matter of editing a single structured file and opening a pull request. The system automatically detects the browser's preferred language but always allows a manual override.

Beyond the UI, the prompt parsing layer understands stylistic hints in multiple natural languages, so you can describe a desired mood in the language you think in most naturally.

Running a training job at 3 a.m. and something looks odd? Our support channels are staffed continuously. Whether you are in Reykjavík, Seoul, or São Paulo, someone with real experience in audio machine learning is available to help you diagnose and resolve issues. Assistance covers configuration reviews, dataset diagnostics, and interpretation of unexpected metrics — not just "have you tried turning it off and on again."

A bird's-eye view of the project's internal geography:

• core/ — the training engine, optimizer choreography, and checkpoint manager.
• ingest/ — dataset scanners, fingerprinting, and manifest builders.
• augment/ — the transform catalog plus probability envelopes.
• condition/ — text, melody, and rhythm embedding adapters.
• dashboard/ — the responsive web interface and its metrics bridge.
• export/ — packaging logic for portable model bundles.
• locales/ — translation files for every supported language.
• docs/ — long-form documentation, diagrams, and tutorials.
• examples/ — ready-to-adapt configuration files for common scenarios.
• tools/ — small utilities for inspecting datasets and checkpoints.

Every folder contains its own focused guide, so you never have to reverse-engineer intent from filenames alone.

Configuration in HarmonicForge is expressed through a single structured file that describes the entire run: data sources, augmentation chain, conditioning mix, optimizer behavior, and delivery preferences. The schema is intentionally verbose — readable by humans first, machines second — because a configuration is also documentation of an experiment.

Layered overrides let you define a base profile and then patch it for specific runs, which keeps repetitive setups from bloating your workspace. Named profiles ship in the examples directory to get you moving quickly, whether you are training on a handful of tracks or a sprawling archive.

We think of a dataset not as a pile of files but as a collection with personality. HarmonicForge therefore spends real effort understanding what you give it: measuring loudness, flagging clipped passages, detecting silent gaps, grouping near-duplicates by acoustic fingerprint, and surfacing an overall health score. You get a report before training begins — not a mystery afterwards.

The tool also nudges you toward good hygiene. If your corpus leans heavily toward one tempo or one key, it will say so. If half your tracks are thirty seconds and half are ten minutes, it will suggest a strategy. It is less a gatekeeper and more a knowledgeable friend looking over your shoulder.

A typical journey through the pipeline looks like this:

1. Scan — Point HarmonicForge at one or more directories; it builds a manifest and health report.
2. Review — Inspect the report, prune or add material, and optionally tag tracks with stylistic labels.
3. Compose a config — Start from an example profile and adjust to taste.
4. Launch — The training loop begins, streaming telemetry to the dashboard.
5. Audition — Listen to periodic samples; adjust augmentation or conditioning if something feels off.
6. Branch — If a promising checkpoint appears, fork the run to explore variations.
7. Export — When satisfied, produce a portable bundle with everything needed to reproduce the result.

Each stage is designed to be interruptible and resumable, so a power outage or a forgotten laptop charger never costs you a week of progress.

Metrics are useful, but ears are the final judge. HarmonicForge integrates a lightweight auditioning ritual: at configurable intervals, the system generates a small set of samples from fixed prompts and presents them side by side with previous epochs. Over time, a growing gallery of these samples becomes an informal history of the model's development — a scrapbook of its musical childhood.

Alongside the listening material, you get quantitative views: loss curves, spectral distance measures, and a perceptual proxy score that correlates reasonably well with human judgments for many genres. Neither replaces the other; together they tell a fuller story.

When a run concludes, HarmonicForge assembles an export bundle containing the model weights, the configuration used, the manifest of training material, and a plain-language summary of the experiment. These bundles are portable, self-describing, and easy to hand to a collaborator who may be running a wholly different environment. Interoperability is a first-class goal: wherever possible, the tool speaks formats that other ecosystems already understand.

HarmonicForge runs on a surprising range of hardware. A single consumer GPU is enough to fine-tune modest models on small corpora. Larger setups unlock bigger batches and faster iteration, but the tool never assumes abundance — it adapts precision, batch sizes, and gradient accumulation to fit what you have. Memory-pressure warnings arrive early and with concrete suggestions, not vague admonitions.

CPU-only operation is possible for very small experiments and for dataset diagnostics, though training itself is best enjoyed with at least one dedicated accelerator.

Planned developments for the 2026 cycle include:

• A richer plugin registry with versioned interfaces.
• Collaborative multi-user dashboards for lab environments.
• Expanded conditioning options for rhythm-first workflows.
• Additional export formats targeting popular interchange standards.
• Enhanced dataset storytelling — automatic narrative summaries of a corpus.
• Broader locale coverage driven by community contributions.

Priorities will always be shaped by what practitioners actually need, so feedback early and often is genuinely welcome.

Is HarmonicForge tied to a single model architecture? No. The training loop is deliberately architecture-agnostic; adapters exist for common families, and new ones can be added without touching the core.

Do I need an enormous dataset? Not at all. The tool excels with small, curated corpora. Quality of material matters far more than raw hours.

Can I pause and resume? Yes. Checkpoints are first-class citizens, and resuming is a routine operation.

Will my audio leave my machine? Only if you choose to share it. Local-first operation is a core principle.

Can I use the dashboard over a network? Yes, with appropriate access controls. Guidance is provided in the documentation.

Is there a way to compare two training runs? The dashboard supports side-by-side comparison of metrics and audition samples.

Contributions of every size are appreciated — from typo fixes to entirely new conditioning adapters. The project follows a straightforward flow: open an issue to discuss substantial changes, keep pull requests focused, and include tests or documentation updates where relevant. A detailed contributing guide lives in the docs folder and covers style expectations, commit conventions, and review etiquette.

If you are unsure where to begin, look for issues tagged as welcoming to newcomers. There is always room for another pair of hands, and the maintainers genuinely enjoy helping first-time contributors land their first change.

HarmonicForge is committed to a welcoming, harassment-free environment for everyone. Participants are expected to communicate with respect, assume good faith, and offer critique that targets ideas rather than people. Reports of unacceptable behavior are handled promptly and confidentially.

This project is released under the MIT License. You are welcome to use, modify, and redistribute it in accordance with the terms of that license. A full copy is included in the repository, and you can also read the canonical text here: MIT License.

Copyright (c) 2026 HarmonicForge Contributors.

HarmonicForge is provided as-is, without warranty of any kind, express or implied. The authors and contributors are not liable for any damages arising from its use. You are solely responsible for ensuring that the audio material you train on is used lawfully and that any resulting outputs comply with applicable rights, licenses, and platform policies. Generative systems can produce unexpected or derivative-sounding results; review outputs carefully before publishing or distributing them. Nothing in this repository constitutes legal advice.

HarmonicForge stands on the shoulders of a vibrant research community exploring generative audio, differentiable signal processing, and human-in-the-loop creative tools. Thanks are due to the many open-source maintainers whose libraries make a project like this feasible, to the translators who broaden its reach, and to the early adopters who filed the first rough-edged bug reports when everything was still held together with optimism and duct tape.

And of course, to you — for reading this far. Now go train something beautiful.