PanoramicData.MusicGeneration
0.1.6
See the version list below for details.
dotnet add package PanoramicData.MusicGeneration --version 0.1.6
NuGet\Install-Package PanoramicData.MusicGeneration -Version 0.1.6
<PackageReference Include="PanoramicData.MusicGeneration" Version="0.1.6" />
<PackageVersion Include="PanoramicData.MusicGeneration" Version="0.1.6" />
<PackageReference Include="PanoramicData.MusicGeneration" />
paket add PanoramicData.MusicGeneration --version 0.1.6
#r "nuget: PanoramicData.MusicGeneration, 0.1.6"
#:package PanoramicData.MusicGeneration@0.1.6
#addin nuget:?package=PanoramicData.MusicGeneration&version=0.1.6
#tool nuget:?package=PanoramicData.MusicGeneration&version=0.1.6
PanoramicData.MusicGeneration
Deterministic, seeded music generation for .NET. A seed becomes a whole song: a key and scale, a tempo, a new chord every bar, a bass line, a tune with optional recurring sections, and a drum pattern, rendered to PCM. It also hands back the list of notes it played, so you can score a pitch tracker, an onset detector or a fingerprinting library against the truth.
- Reproducible for ever. The same seed, length, sample rate and style give the same song on any machine and any .NET version: the library carries its own random number generator (PCG32) and its own bit-exact sine.
- Varied. Tempo, key, scale, harmony, melody, drum pattern, timbre, tuning and lead-in all come from the seed. The default free-running mode avoids exact loops; opt into a form for returning verses and choruses.
- Ground truth included. Every note and drum hit comes back with its start, length, MIDI note and rendered frequency.
- No samples, no copyright. Everything is synthesised from sine waves and noise by arithmetic you can read in an afternoon.
- Educational. The demo site explains the maths: equal temperament, harmonics, envelopes, noise and the random number generator.
Try it in your browser: the demo runs the whole library locally (once published, at the address shown in the repository's About box). See docs/DEMO.md.
Installation
dotnet add package PanoramicData.MusicGeneration
Targets .NET 10. Not yet published to NuGet.
Quick start
using PanoramicData.MusicGeneration;
// 30 seconds of music at 22,050 Hz from seed 42.
GeneratedSong song = SongGenerator.Generate(seed: 42, seconds: 30, sampleRate: 22050);
float[] samples = song.Samples; // mono, loudest sample exactly 0.9
byte[] wav = song.ToWav(); // 16-bit mono WAV, ready to save or play
Console.WriteLine($"{song.Info.TempoBpm} bpm, {Pitch.NameOf(song.Info.RootMidi)} {song.Info.ScaleName}");
foreach (var note in song.Notes.Where(n => n.Voice == VoiceKind.Melody).Take(5))
{
Console.WriteLine($"{note.StartSeconds:0.00}s {Pitch.NameOf(note.MidiNote)} {note.FrequencyHz:0.0} Hz for {note.DurationSeconds:0.00}s");
}
Choose what may vary, or switch parts off, with a SongStyle:
var style = new SongStyle
{
MinTempoBpm = 100, MaxTempoBpm = 120,
Scales = [Scales.MinorPentatonic, Scales.Dorian],
MelodyLowMidi = 60, MelodyHighMidi = 84, // middle C to C6
Drums = false // no drums
};
var song = SongGenerator.Generate(7, 20, 44100, style);
Capture tracks once for a mute/solo UI:
var song = SongGenerator.GenerateStems(42, 10, 11025);
double[] melody = song.Stems[VoiceKind.Melody]; // before normalisation
// Sum the desired stems, then apply song.NormalisationGain.
SongStyle.Kick, Snare and HiHat independently gate the drums. PadOctaveOffset, PadLevel and PadAttackSeconds control the quieter pad. VibratoDepth, VibratoMinHz, VibratoMaxHz, VibratoDelaySeconds and VibratoRampSeconds control the singer; depth zero disables vibrato. Algorithm version 2 changes the sound for existing seeds; see the algorithm history.
Recurring sections
Use an explicit form for an intro, A-B-A-B-C-B and an outro:
var style = new SongStyle { Form = SongForms.VerseChorus };
var song = SongGenerator.Generate(42, 60, 11025, style);
foreach (var section in song.Sections)
{
Console.WriteLine($"{section.Kind} {section.MaterialId}: {section.StartSeconds:0.00}-{section.EndSeconds:0.00}s");
}
Matching material identities reuse the written pattern. Each occurrence can change melody register, density and active voices, or add pickups and transition fills. Forms round-trip through System.Text.Json; each note identifies its source section. The example fits whole bars at the chosen tempo; short requests may omit later sections. See section composition for duration and ending rules.
What a song contains
| Part | How it is made |
|---|---|
| Pad | One triad per bar on a random scale degree with a random inversion; 2 soft harmonics, slow attack and decay, folded below the melody. |
| Bass | A note on most beats: the chord root, sometimes its fifth; low, 3 harmonics, quick decay. |
| Melody | A random walk through the scale, clamped to the melody range, with half, one or one-and-a-half beat notes, 15% rests, 6 harmonics and a gentle vibrato. |
| Kick | A sine whose frequency falls as <code>f<sub>0</sub> + 110 e<sup>-28t</sup></code>. |
| Snare, hi-hat | White noise through a first-difference filter times a fast decay. |
Full description, formulas and parameters: docs/DESIGN.md.
Determinism
Reproducibility is the point, so it is tested hard: a golden hash of a generated song, golden values for the random number generator (they match the published PCG32 reference outputs), and a check that changing the sample rate does not change the notes. SongGenerator.Version names the algorithm version; any change that alters the output for an existing seed is a breaking change and increments it.
If arithmetic speed matters more than bit-exactness (for example in an interpreted WebAssembly runtime, where the library's own sine is slow), set SongStyle.UsePlatformSine. The notes and choices are unchanged; only the last bit of each sample may then differ between operating systems.
Documentation
| Document | For |
|---|---|
| docs/DESIGN.md | Goals, algorithm, parameters, determinism contract, API |
| docs/DEMO.md | The browser demo and how to host it |
| docs/DEVELOPMENT_PROMPT.md | The brief for developing the library further |
Development
dotnet build # warnings are errors
dotnet test --project PanoramicData.MusicGeneration.Test
dotnet run --project PanoramicData.MusicGeneration.Demo
The library has unit tests for synthesis, voice independence and raw stem reconstruction. Contributions: see CONTRIBUTING.md and SECURITY.md.
Links
- NuGet: https://www.nuget.org/packages/PanoramicData.MusicGeneration (once published)
- Source: https://github.com/panoramicdata/PanoramicData.MusicGeneration
- Issues: https://github.com/panoramicdata/PanoramicData.MusicGeneration/issues
License
MIT, see LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages (1)
Showing the top 1 NuGet packages that depend on PanoramicData.MusicGeneration:
| Package | Downloads |
|---|---|
|
PanoramicData.MusicGeneration.SoundFonts
Optional SoundFont instrument-bank rendering for PanoramicData.MusicGeneration using MeltySynth. Caller-supplied SF2 assets, inspectable replay metadata and independent stems. |
GitHub repositories
This package is not used by any popular GitHub repositories.