vgm2midi

A modern, accurate CLI tool to convert VGM/VGZ (Video Game Music) files to MIDI format. Compatible with macOS, Linux, and Windows.

Features

• Accurate Timing: Uses explicit Note On/Off events with precise sub-tick delta timing for rock-solid synchronization.
• Hybrid Pitch Handling:
  • Uses Pitch Bends for small frequency changes (vibrato, slides, detuning) to prevent "machine gun" re-triggering.
  • Uses Note Retriggering for distinct melody steps, ensuring clear articulation.
  • Channel-specific tuning (e.g., wider slide range for Bass, tighter precision for Melody).
• Dynamic Volume: Maps chip volume changes to MIDI Expression (CC#11), preserving the original ADSR envelopes, decays, and swells.
• Percussion Mapping: Automatically maps SN76489 Noise channel to MIDI Channel 10 (Percussion) with frequency-to-drum mapping (Kick, Snare, Hi-Hats).
• Glitch Suppression: Intelligent look-ahead logic filters out artifacts from split-byte chip commands (preventing the "double-tap" glitch).
• Multi-Track Output: Generates a dedicated MIDI track for every internal sound chip channel (e.g., SN76489 Tone 0, YM2612 FM 5).
• Format Support:
  • VGM and VGZ (gzip-compressed) files.
  • SN76489 PSG, YM2612 FM, YM2413 FM, YM2151 FM, AY-3-8910 PSG.

Installation

From npm (once published)

npm install -g vgm2midi

From source

git clone <repository-url>
cd vgm2midi
npm install
npm run build
npm link

Usage

Basic conversion

vgm2midi input.vgm

This creates input.mid in the same directory.

Specify output file

vgm2midi input.vgm -o output.mid

Set custom tempo

vgm2midi input.vgm --tempo 140

Verbose output

vgm2midi input.vgm -v

This shows:

• VGM version
• Duration
• Detected sound chips
• Total commands processed

Convert VGZ (compressed) files

VGZ files are automatically detected and decompressed:

vgm2midi song.vgz

Command-line Options

Usage: vgm2midi [options] <input>

Convert VGM/VGZ (Video Game Music) files to MIDI format

Arguments:
  input                   Input VGM or VGZ file

Options:
  -V, --version          output the version number
  -o, --output <file>    Output MIDI file (default: input filename with .mid extension)
  -t, --tempo <bpm>      MIDI tempo in BPM (default: "120")
  -v, --verbose          Verbose output
  -h, --help             display help for command

Programmatic API

You can also use vgm2midi as a library in your Node.js projects:

import { convertVGMToMidi, VGMParser, MidiConverter } from 'vgm2midi';

// Simple conversion
convertVGMToMidi('input.vgm', 'output.mid', {
  tempo: 120,
  verbose: true
});

// Advanced usage
const parser = VGMParser.fromFile('input.vgm');
const vgmData = parser.parse();

console.log(`Duration: ${vgmData.header.totalSamples / 44100} seconds`);
console.log(`Commands: ${vgmData.commands.length}`);

const converter = new MidiConverter(vgmData, { tempo: 140 });
converter.exportToFile('output.mid');

How it Works

The converter performs these steps:

1. Parse VGM file: Reads the VGM header and extracts sound chip information
2. Decompress if needed: Automatically handles VGZ (gzipped VGM) files
3. Process commands: Interprets chip register writes and timing commands
4. Convert to MIDI: Translates chip frequencies and volumes to MIDI note events
5. Write MIDI file: Outputs a standard MIDI file

Conversion Details

• VGM files log sound chip commands at 44.1 kHz sample accuracy
• The converter extracts note on/off events and durations
• PSG (Programmable Sound Generator) tone channels are mapped to MIDI channels 1-3
• FM synthesis channels use MIDI channels 5-10
• Frequency values are converted to MIDI note numbers using: note = 69 + 12 * log2(freq / 440)

Limitations

• FM synthesis parameters are simplified (MIDI doesn't support FM)
• Noise channels are not currently converted
• Some complex chip features may not translate perfectly to MIDI
• Percussion and special effects may sound different

VGM File Format

VGM (Video Game Music) is a sample-accurate logging format for video game console audio. It records the exact commands sent to sound chips during gameplay. The format supports numerous sound chips from various gaming platforms.

For more information, see the VGM specification.

Development

Build

npm run build

Run without building

npm run dev -- input.vgm -v

Project Structure

src/
├── types.ts          # TypeScript interfaces
├── vgm-parser.ts     # VGM file parser
├── midi-converter.ts # VGM to MIDI conversion logic
├── cli.ts            # Command-line interface
└── index.ts          # Public API exports

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Credits

• VGM format specification: VGMRips Wiki
• MIDI library: midi-writer-js

Related Projects

• vgmplay - VGM file player
• vgm2ogg - Convert VGM to OGG
• VGMTrans - Video game music conversion tool