🥮 mooncakes.io

moonsic

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

moonbit
music
midi
musicxml
wav
moon add hyl-star/moonsic@0.1.0
Download zip
Author
Version
0.1.0
License
Apache-2.0
Repository
Last updated
last month
Downloads
10

Dependencies

README

#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.mbtMeasure/Voice/Staff/Part/ScoreLayout
score_enhanced.mbtSection/Repeat/Ending/Notation/Lyric/Tie
validate.mbtValidationProfile + 导出就绪校验

#生成

模块内容
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

FunctionResultMIDI
c(4)..b(4)natural60-71
cs(4)..gs(4)sharp61-68
db(4)..bb(4)flat61-70

#Events

FunctionDescription
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 min7Other chords

#Track & Score

FunctionDescription
melody([...])Create track
score1(t)Single-track score
score_with([tracks], bpm, ts)Multi-track score
track.transpose/stretch/concat/reverseTransforms

#Theory

FunctionDescription
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 / arpeggiateGenerators

#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

FunctionOutput
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

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io