引言

在数字音乐的世界里，MIDI（Musical Instrument Digital Interface）就像是音乐的"基因密码"。作为直男程序员，我最近使用.NET 9.0 C# 写了一个命令行 MIDI 播放器，用来增加自己的情绪价值。本文将分析这个有趣的开源项目 Edi.MIDIPlayer，它不仅能播放MIDI音乐，还能实时显示每一个音符的"生命轨迹"。

什么是 MIDI？

MIDI 格式介绍

MIDI 并不是音频文件，而是一种指令协议，一种面向电子乐器、计算机和其他相关设备的标准通讯协议与数据格式。想象一下，如果音频文件是录制好的演奏录音，那么 MIDI 就是乐谱上的指令。MIDI 协议定义了乐器与乐器、乐器与电脑之间的数字信息传输方式，但它本身并不直接包含声音数据，而是传递“事件信息”（例如：演奏某个音符、控制某个参数、开始/停止等），例如：

  • 何时 按下哪个键（Note On 事件）
  • 多大力度 按下（Velocity，0-127）
  • 何时 松开键（Note Off 事件）
  • 哪个通道 发出声音（Channel，支持16个通道）
  • 用什么乐器 演奏（Program Change）

MIDI 广泛应用于音乐制作、游戏音效、电子乐器等领域。它的优势在于文件小、易于编辑和实时控制。

标准 MIDI 文件（SMF，Standard MIDI File）由三部分组成：

1 Header Chunk

标记为"MThd"，存储文件类型（0/1/2）、轨道数量、时间单位（Ticks per Quarter Note，TPQN）

2 Track Chunk

标记为"MTrk"

每个 Track 为一个 MIDI 数据流，内容为一组有时间戳标记的 MIDI 事件（例如演奏音符、控件变化）。

  • 类型0：单一轨道
  • 类型1：多轨道（常见于编曲，有主控轨+乐器轨）
  • 类型2：多序列轨道，罕见

3 MIDI 事件

  • 频道消息（Channel Messages）：音符开/关、力度、控制器、乐器选择等
  • 系统消息（System Messages）：同步、元事件（如歌词、节拍、作者信息等）

MIDI 文件示例

4D 54 68 64    // "MThd" Header
00 00 00 06    // Head Size = 6
00 01          // Type 1 (多轨道)
00 02          // 两个轨道
00 60          // 96 ticks/quarter note

4D 54 72 6B    // "MTrk" Track
00 00 00 30    // Track Size

00 90 3C 64    // DeltaTime=0, Note On, middle C, velocity 100
81 40 80 3C 40 // DeltaTime=192, Note Off, middle C, velocity 64
...

好消息是，我们不需要自己 996 实现 MIDI 文件的解析，这个播放器程序使用 NAudio 库来处理 MIDI 文件。

乐理知识的代码实现

音符

在深入代码之前，我们需要了解一些音乐基础：

  1. 音符命名：C、C#、D、D#、E、F、F#、G、G#、A、A#、B（12个半音）
  2. 八度：每12个半音为一个八度，中央C为C4
  3. MIDI音符编号：0-127，其中60号是中央C（C4）

在代码中，我们可以看到音符名称的转换逻辑：

private static readonly Dictionary<int, string> NoteNames = new()
{
    { 0, "C" }, { 1, "C#" }, { 2, "D" }, { 3, "D#" }, { 4, "E" }, { 5, "F" },
    { 6, "F#" }, { 7, "G" }, { 8, "G#" }, { 9, "A" }, { 10, "A#" }, { 11, "B" }
};

public string GetNoteName(int noteNumber)
{
    var octave = (noteNumber / 12) - 1;  // 计算八度
    var note = NoteNames[noteNumber % 12];  // 计算音符名称
    return $"{note}{octave}";
}

这个算法巧妙地将 MIDI 音符编号转换为我们熟悉的音符名称。例如：

  • 音符60 → 60 % 12 = 0 (C), 60 / 12 - 1 = 4 → "C4"
  • 音符73 → 73 % 12 = 1 (C#), 73 / 12 - 1 = 5 → "C#5"

节拍

节拍，是乐理中的一个重要概念，用于表示音乐中强弱规律的循环。

乐谱开头通常会标注一个拍号，比如“4/4”、“3/4”，这表示每小节有多少拍（上数字），以及每一拍用了哪种音符（下数字，例如“4”代表四分音符）。

在 MIDI 文件中，节拍的相关参数主要通过一种特殊的元事件（Meta Event）来表示，这个事件叫做“节拍事件”（Set Tempo）和“时基（PPQN／TPQN）”，“但严格来说，拍号（Time Signature）表示的是每小节包含的拍数和每拍的音符类型”。

MIDI 文件内部不直接用秒来表示时间，而是用“Tick”（时基）单位。Tick数取决于MIDI文件头中设定的“PPQN”（Parts Per Quarter Note，四分音符每分多少Tick）。例如：如果PPQN设为480，则一个四分音符等于480 Tick。

通过Meta事件类型 0xFF 0x51，设置每个四分音符的微秒数，从而间接决定每分钟的节拍数（BPM）。

拍号/节拍事件用 Meta Event 类型 0xFF 0x58 表示，一般描述每小节有几拍，每拍是什么音符类型，与乐理中的拍号类似。

程序里需要将 Tick 转换为实际时间：

public TimeSpan TicksToTimeSpan(long ticks, List<TempoChange> tempoMap, int ticksPerQuarterNote)
{
    var totalMicroseconds = 0.0;
    var currentTick = 0L;

    for (int i = 0; i < tempoMap.Count; i++)
    {
        var tempoChange = tempoMap[i];
        var nextTick = (i + 1 < tempoMap.Count) ? tempoMap[i + 1].Tick : ticks;

        if (nextTick > ticks) nextTick = ticks;

        if (nextTick > currentTick)
        {
            var ticksInThisSegment = nextTick - currentTick;
            var microsecondsPerTick = (double)tempoChange.MicrosecondsPerQuarterNote / ticksPerQuarterNote;
            totalMicroseconds += ticksInThisSegment * microsecondsPerTick;
        }

        currentTick = nextTick;
        if (currentTick >= ticks) break;
    }

    return TimeSpan.FromMilliseconds(totalMicroseconds / 1000.0);
}

这个算法处理了 MIDI 中的变速情况——一首曲子中可能有多个速度变化，每个段落都需要用不同的时间计算公式。

程序还需要构建整个 MIDI 文件的速度变化映射表，查找类型为 MetaEvent 且子类型为 SetTempo 的事件，并记录速度变化：

tempoMap.Add(new TempoChange
   {
       Tick = eventInfo.AbsoluteTime,  // 速度变化的时钟位置
       MicrosecondsPerQuarterNote = tempoEvent.MicrosecondsPerQuarterNote  // 新的速度值
   });

这对于准确播放 MIDI 文件至关重要，确保音乐按照正确的速度和节拍进行播放。

程序架构解析

依赖注入与服务架构

这个MIDI播放器采用了现代.NET的最佳实践，使用了依赖注入来管理各个组件：

private static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.AddSingleton<IConsoleDisplay, ConsoleDisplayService>();
            services.AddSingleton<IInputHandler, InputHandlerService>();
            services.AddSingleton<ITempoManager, TempoManagerService>();
            services.AddSingleton<INoteProcessor, NoteProcessorService>();
        });

整个系统分为几个核心服务：

  • ConsoleDisplayService：负责所有的控制台输出和视觉效果
  • TempoManagerService：处理MIDI的节拍和时间计算
  • NoteProcessorService：处理音符事件的显示逻辑
  • MidiPlayerService：核心播放逻辑

实时MIDI事件处理

程序的核心在于如何准确地按时间播放 MIDI 事件。让我们看看这个精巧的时间控制算法：

private async Task PlayEventsAsync(List<MidiEventInfo> allEvents, IMidiDeviceWrapper midiDevice, int ticksPerQuarterNote)
{
    var stopwatch = Stopwatch.StartNew();
    var playbackStart = stopwatch.Elapsed;

    foreach (var midiEntry in allEvents)
    {
        // 计算这个事件的预期播放时间
        var expectedTime = playbackStart.Add(tempoManager.TicksToTimeSpan(midiEntry.AbsoluteTime, tempoMap, ticksPerQuarterNote));
        var currentTime = stopwatch.Elapsed;

        // 等待直到该播放这个事件
        var delayNeeded = expectedTime - currentTime;
        if (delayNeeded > TimeSpan.Zero)
        {
            await Task.Delay(delayNeeded);
        }

        ProcessMidiEvent(midiEntry, midiDevice, stopwatch, activeNotes);
    }
}

这里的关键是精确的时间同步：

  1. 使用 Stopwatch 获得高精度计时
  2. 计算每个 MIDI 事件的绝对播放时间
  3. 使用 Task.Delay 进行非阻塞等待
  4. 确保音乐按照正确的节拍播放

视觉魔法：让音乐可见

实时力度

最有趣的功能之一是力度条的显示。每个音符的演奏力度（0-127）会被转换为彩色的条形图：

public string CreateVelocityBar(int velocity)
{
    var barLength = 10;
    var filledLength = (int)((velocity / 127.0) * barLength);
    var bar = new StringBuilder();

    for (int i = 0; i < barLength; i++)
    {
        if (i < filledLength)
        {
            if (i < 3) Console.ForegroundColor = ConsoleColor.Green;      // 轻柔
            else if (i < 7) Console.ForegroundColor = ConsoleColor.Yellow; // 中等
            else Console.ForegroundColor = ConsoleColor.Red;              // 强烈
            bar.Append('█');
        }
        else
        {
            Console.ForegroundColor = ConsoleColor.DarkGray;
            bar.Append('░');
        }
    }
    
    return bar.ToString();
}

这样，我们就能直观地看到音乐的动态变化：

VEL:0x4F ██████░░░░  // 中等力度
VEL:0x7F ██████████  // 最大力度
VEL:0x20 ███░░░░░░░  // 轻柔力度

彩色音符显示

程序还根据音符类型显示不同颜色：

public ConsoleColor GetNoteColor(int noteNumber)
{
    return (noteNumber % 12) switch
    {
        0 or 2 or 4 or 5 or 7 or 9 or 11 => ConsoleColor.White,  // 自然音（白键）
        _ => ConsoleColor.Magenta  // 升降音（黑键）
    };
}

这个设计模拟了钢琴键盘的布局，白键音符显示为白色，黑键音符显示为紫色。

控制台输出的实时同步

线程安全的输出

由于 MIDI 事件可能来自多个通道，程序使用了锁机制确保输出的一致性：

lock (consoleDisplay.GetConsoleLock())
{
    Console.Write("[");
    Console.ForegroundColor = ConsoleColor.DarkGray;
    Console.Write(timestamp);
    Console.ResetColor();
    Console.Write("] ");

    Console.ForegroundColor = ConsoleColor.Green;
    Console.Write("▲ NOTE_ON  ");
    // ... 更多输出逻辑
}

信息密度的平衡

每行输出都包含了丰富的信息，但又保持了很好的可读性：

[14:23:45.123] ▲ NOTE_ON  C4   CH01 VEL:0x64 ████████░░ │ ACTV: 0x03 │ NOTE: 0x3C
[14:23:45.823] ▼ NOTE_OFF C4   CH01 VEL:0x00 ░░░░░░░░░░ │ ACTV: 0x02 │ NOTE: 0x3C

这行输出告诉我们：

  • 时间戳：精确到毫秒的播放时间
  • 事件类型：▲表示按键，▼表示释放
  • 音符信息：C4 表示中央C
  • 通道信息：CH01 表示第1通道
  • 力度信息：0x64 表示中等力度，用条形图可视化
  • 状态信息：当前活跃音符数量和原始 MIDI 数据

结语

这个 MIDI 播放器不仅仅是一个播放工具，更是一个音乐数据的实时可视化器。它让我们能够"看见"音乐的流动，理解 MIDI 数据的结构，体验数字音乐的魅力。

通过这个项目，我们学到了：

  • MIDI 格式的内部结构
  • 精确时间控制的编程技巧
  • 控制台应用的视觉设计
  • 现代 .NET 的最佳实践

无论你是音乐爱好者还是程序员，这个项目都展示了技术与艺术结合的美妙可能性。下次当你听到 MIDI 音乐时，不妨想象一下背后那些精密的数字指令，它们正在控制着每一个音符的生命周期。

源代码地址：https://github.com/EdiWang/Edi.MIDIPlayer