README

moonsic

A MoonBit music IR and interoperability library with MIDI, MusicXML, WAV, and browser event export.

moonbit

music

midi

musicxml

wav

Download zip

Author

hyl-star

Version

0.1.0

License

Apache-2.0

Repository

github.com/hyl-star/moonsic

Last updated

3 months ago

Downloads

#moonsic

MoonBit 音乐语义库 — 用强类型描述音乐，导出 MIDI/WAV/浏览器事件。

v2 多包架构已发布。 v1 根包 API 已弃用，请参考 MIGRATION.md 迁移。

#v2 多包架构 (25 packages)

packages/
  pitch/      音高 + 快捷构造 + MIDI/频率 + 解析
  interval/   音程计算 + 转位 + 解析
  time/       节奏时间 + RhythmDuration + TimeSignature
  scale/      音阶 + 调性 + Key
  chord/      和弦品质 + 解析 + 展开
  harmony/    罗马数字 + 声部引导
  rhythm/     节奏模板 + 模式 + Phrase
  motif/      音级动机 + 变换
  score/      SimpleScore + ScoreLayout + 构造器
  validation/ 校验报告 + profile
  json/       零依赖 JSON 解析/序列化
  parse/      统一解析 facade
  midi/       MIDI 事件 + 排序 + 字节导出 + GM 乐器
  musicxml/   MusicXML 模型 + 转换 + 字符串写入
  timeline/   NoteEvent 时间线 + 浏览器事件导出
  wav/        WAV 渲染
  game/       游戏音乐 IR
  generate/   旋律/和弦/bass/伴奏生成
  adapter/    外部生成器协议
  drums/      GM 鼓组 + 基本节拍
  transform/  SimpleTrack 纯变换
  structure/  歌曲段落 + arrange
  ffi/        string-in/string-out facade
  demo/       端到端作曲流水线

#快速开始 (v2)

///| 导入所需包（moon.pkg 中配置）

///| import: pitch, time, score, midi

///|
let p = @pitch.c(4) // C4

///|
let dur = @time.rhythm_duration(@time.DurQuarter, 0, None)

///|
let vel = @score.velocity_checked(100).unwrap()

///|
let n = @score.simple_note_checked(p, dur, Some(vel)).unwrap()

///|
let track = @score.simple_track_checked([n], None, None).unwrap()

///|
let tempo = @score.tempo_checked(120).unwrap()

///|
let sig = @time.time_signature(4, 4)

///|
let score = @score.simple_score_checked([track], tempo, sig).unwrap()

///|
let midi = @midi.simple_score_to_midi_bytes_checked(score, 480).unwrap()

#v1 快速开始（已弃用）

///|
let chords = progression(c(3), Major, [I, V, VI, IV], half())

///|
let lead = melody_str("C4q D4q E4q G4q")

///|
let song = score_with([chords, lead], 120, four_four())

///|
let midi = song.to_midi_bytes() // MIDI 字节流

///|
let wav = song.to_wav_bytes() // WAV 音频

#核心概念

Pitch — 音高 = 音名 + 变音记号 + 八度，@pitch.c(4) = C4 (MIDI 60)
RhythmDuration — 时值：@time.rhythm_duration(unit, dots, tuplet)
SimpleEvent — 轨道事件：Note | Rest | Chord (在 @score 包)
SimpleTrack — 有序事件序列，带 channel/program/volume/pan/mute
SimpleScore — 速度 + 拍号 + 多轨道
NoteEvent — 运行时事件：start/duration/midi/velocity/channel (在 @timeline 包)

数据流 (v2)：

@score.SimpleScore → @midi / @musicxml / @timeline → @wav / Browser / Bytes

#API 速览

#音高

函数	结果	MIDI
c(4) d(4) e(4) f(4) g(4) a(4) b(4)	自然音	60~71
cs(4) ds(4) fs(4) gs(4)	升号	61~68
db(4) eb(4) gb(4) ab(4) bb(4)	降号	61~70
pitch(C, Sharp, 4)	完整构造	—

#时值

函数	拍数
whole()	4.0
half()	2.0
quarter()	1.0
eighth()	0.5
sixteenth()	0.25
dotted(quarter())	1.5

#事件

函数	说明
n(c(4), quarter())	音符（力度100）
nv(c(4), quarter(), 64)	指定力度
r(half())	休止
major(c(3), half())	大三和弦
minor(a(3), half())	小三和弦
dim aug dom7 maj7 min7	其他和弦
ch([c(4),e(4),g(4)], q())	自定义和弦

#轨道与乐谱

函数	说明
melody([...])	创建轨道
score1(track)	单轨乐谱
score_with([tracks], bpm, ts)	多轨乐谱
track.transpose(n)	移调
track.stretch(f) track.concat track.reverse	变换

#乐理

函数	说明
scale(root, kind, octaves)	音阶
degree(root, kind, n)	第N级
progression(root, kind, [I,IV,V], dur)	和弦进行
roman_progression(key, "I V vi IV", dur)	文本进行
voice_lead(chords)	声部引导
bass_from_progression(chords, style, oct)	低音
arpeggiate(chords, step_dur)	琶音

#文本记谱

///|
let t = melody_str("C4q D4q [E4 G4]h Rq D4q:64 x2")

///|
let s = score_str("tempo 140\ntime 3/4\nC4q D4q E4q")

格式：音名[变音][八度]时值[:力度]。和弦：[音1 音2...]时值。重复：xN。

#导出

函数	输出
song.to_midi_bytes()	MIDI 字节流 (SMF Format 1)
song.to_wav_bytes()	WAV 字节流 (44100Hz 16-bit mono)
score_to_json(song)	JSON 字符串
score_to_musicxml_string_checked(s, opts)	MusicXML 字符串

#曲谱结构（进阶）

模块	内容
score_layout.mbt	Measure/Voice/Staff/Part/ScoreLayout
score_enhanced.mbt	Section/Repeat/Ending/Notation/Lyric/Tie
validate.mbt	ValidationProfile + 导出就绪校验

#生成

模块	内容
generate.mbt	旋律/和弦/bass/伴奏/游戏循环生成
rhythm.mbt	节奏模板/动机/模式变换

#协议

模块	内容
adapter.mbt	外部生成器协议 (GenerationRequest/Response)
game_music.mbt	游戏音频 IR (Cue/Loop/Stinger/Transition)

#项目结构 (v2)

moon.pkg               根包（空）
moon.mod.json          模块元数据
packages/              24 个子包
  pitch/              音高 + 快捷构造 + MIDI/频率 + 解析
  interval/           音程计算 + 转位 + 解析
  time/               节奏时间 + RhythmDuration + TimeSignature
  scale/              音阶 + 调性 + Key
  chord/              和弦品质 + 解析 + 展开
  harmony/            罗马数字 + 声部引导
  rhythm/             节奏模板 + 模式 + Phrase
  motif/              音级动机 + 变换
  score/              SimpleScore + ScoreLayout + 构造器
  validation/         校验报告 + profile
  json/               零依赖 JSON 解析/序列化
  parse/              统一解析 facade
  midi/               MIDI 事件 + 排序 + 字节导出 + GM 乐器
  musicxml/           MusicXML 模型 + 转换 + 字符串写入
  timeline/           NoteEvent 时间线 + 浏览器事件导出
  wav/                WAV 渲染
  game/               游戏音乐 IR + 校验 + JSON 导出
  generate/           旋律/和弦/bass/伴奏/loop 生成
  adapter/            外部生成器请求/响应/补丁
  drums/              GM 鼓组 + 基本节拍
  transform/          SimpleTrack 纯变换
  structure/          歌曲段落 + arrange
  ffi/                string-in/string-out facade
  demo/               端到端作曲流水线
cmd/main/             CLI 入口
web/                  浏览器编辑器 + 播放器

#可运行 CLI demo

默认 demo 会通过 packages/demo 的端到端管线生成乐谱、MIDI、MusicXML、WAV、浏览器事件和游戏 IR，并输出不含二进制内容的 JSON 摘要：

moon update
moon run cmd/main

预期输出包含 "has_midi":true、"has_musicxml":true 和 "has_wav":true。

#命令

moon check         # 静态检查
moon test          # 运行测试套件
moon run cmd/main  # 运行端到端 CLI demo
moon fmt           # 格式化
moon info          # 更新接口

#API 稳定性

Stable：Pitch/Duration 构造器、事件构造器、Track/Score 构造、Music 操作（transpose/stretch/repeat/concat）、Render/export（to_midi_bytes/to_wav_bytes）、核心类型

Experimental：melody_str/score_str、roman_progression/accompany/voice_lead、Bass/Arpeggio 生成器、Style 枚举、newv1plus 模块

#moonsic

MoonBit music IR and export library with MIDI, WAV, and browser event output.

v2 multi-package architecture released. See MIGRATION.md for v1 to v2 migration.

#v2 Multi-Package Architecture (25 packages)

packages/
  pitch/      pitch classes, shortcuts, MIDI/frequency, parsing
  interval/   interval quality, calculation, inversion, parsing
  time/       rational time, RhytDuration, TimeSignature
  scale/      scales, keys
  chord/      chord qualities, parsing, pitch expansion
  harmony/    roman numerals, voice leading
  rhythm/     rhythm cells, patterns, phrase fitting
  motif/      degree motifs, transforms, track conversion
  score/      SimpleScore, ScoreLayout, constructors
  validation/ validation reports, profiles
  json/       zero-dependency JSON parse/stringify
  parse/      unified parse-to-JSON facade
  midi/       MIDI events, sorting, bytes export, GM instruments
  musicxml/   MusicXML model, conversion, string writer
  timeline/   NoteEvent timeline, browser event export
  wav/        WAV rendering
  game/       game music IR, validation, JSON export
  generate/   melody, chords, bass, accompaniment generation
  adapter/    external generator request/response/patch
  drums/      GM drum helpers, basic beat generation
  transform/  pure SimpleTrack transforms
  structure/  song sections, arrangement
  ffi/        string-in/string-out facade
  demo/       end-to-end composition pipeline

#Quick Start (v2)

///| Import required packages in moon.pkg

///| import: pitch, time, score, midi

///|
let p = @pitch.c(4)

///|
let dur = @time.rhythm_duration(@time.DurQuarter, 0, None)

///|
let vel = @score.velocity_checked(100).unwrap()

///|
let n = @score.simple_note_checked(p, dur, Some(vel)).unwrap()

///|
let track = @score.simple_track_checked([n], None, None).unwrap()

///|
let tempo = @score.tempo_checked(120).unwrap()

///|
let sig = @time.time_signature(4, 4)

///|
let score = @score.simple_score_checked([track], tempo, sig).unwrap()

///|
let midi = @midi.simple_score_to_midi_bytes_checked(score, 480).unwrap()

#v1 Quick Start (deprecated)

///|
let chords = progression(c(3), Major, [I, V, VI, IV], half())

///|
let lead = melody_str("C4q D4q E4q G4q")

///|
let song = score_with([chords, lead], 120, four_four())

///|
let midi = song.to_midi_bytes()

///|
let wav = song.to_wav_bytes()

#Core Concepts

Pitch — class + accidental + octave, @pitch.c(4) = C4 (MIDI 60)
RhythmDuration — @time.rhythm_duration(unit, dots, tuplet)
SimpleEvent — Note | Rest | Chord (in @score package)
SimpleTrack — ordered events with channel/program/volume/pan/mute
SimpleScore — tempo + time signature + tracks
NoteEvent — runtime event: start/duration/midi/velocity/channel (in @timeline package)

Pipeline (v2): @score.SimpleScore → @midi / @musicxml / @timeline → @wav / Browser / Bytes

#Pitch Shortcuts

Function	Result	MIDI
c(4)..b(4)	natural	60-71
cs(4)..gs(4)	sharp	61-68
db(4)..bb(4)	flat	61-70

#Events

Function	Description
n(p, d)	Note with default velocity
nv(p, d, v)	Note with velocity
r(d)	Rest
major(r, d) / minor(r, d)	Triads
dim aug dom7 maj7 min7	Other chords

#Track & Score

Function	Description
melody([...])	Create track
score1(t)	Single-track score
score_with([tracks], bpm, ts)	Multi-track score
track.transpose/stretch/concat/reverse	Transforms

#Theory

Function	Description
scale(root, kind, n)	Build scale
degree(root, kind, n)	Nth degree
progression(root, kind, rns, dur)	Chord progression
roman_progression(key, text, dur)	Text-based progression
voice_lead(chords)	Voice leading
bass_from_progression / arpeggiate	Generators

#Text Notation

///|
let t = melody_str("C4q D4q [E4 G4]h Rq D4q:64 x2")

Format: Note[Accidental]OctaveDuration[:Velocity]. Chord: [P1 P2...]Dur. Repeat: xN.

#Export

Function	Output
song.to_midi_bytes()	MIDI bytes (SMF Format 1)
song.to_wav_bytes()	WAV bytes (44100Hz 16-bit mono)
score_to_json(song)	JSON string
score_to_musicxml_string_checked(s, opts)	MusicXML string

#Project Structure (v2)

moon.pkg               root package (empty)
moon.mod.json          module metadata
packages/              24 sub-packages (see v2 section above)
cmd/main/              CLI entrypoint
web/                   browser editor + player

#Runnable CLI demo

The default demo runs the packages/demo end-to-end pipeline, producing score, MIDI, MusicXML, WAV, browser-event, and game-IR assets. It prints a JSON summary without binary payloads:

moon update
moon run cmd/main

The output includes "has_midi":true, "has_musicxml":true, and "has_wav":true.

#Commands

moon check         # static check
moon test          # run the test suite
moon run cmd/main  # run the end-to-end CLI demo
moon fmt
moon info

Install

Download zip

A MoonBit music IR and interoperability library with MIDI, MusicXML, WAV, and browser event export.

moonbitmusicmidimusicxmlwav

hyl-star

Apache-2.0

github.com/hyl-star/moonsic

Updated 3 months ago

63 downloads

Site source Report issue Modules Skills CLI Build queue Statistics