FYM to Audio Converter

A collection of Node.js scripts for batch converting .fym (Free YM) chiptune tracker files into standard audio formats like .wav and .mp3.

It utilizes the pure JavaScript audio emulation components fym.js and ayumi.js to accurately simulate the Yamaha YM2149 / Zilog AY-3-8910 programmable sound generators (PSG) and encode the resulting floating point samples natively to disk.

Setup

Ensure you have Node.js installed. Drop your .fym files into an input/ directory before running.

FFmpeg Requirement (for MP3)

The fym-convert-mp3 tool requires FFmpeg to be installed and available in your system's PATH.

• Download: ffmpeg.org
• Installation Tips:
  • Windows: Download the windows build, extract the bin/ folder, and add it to your Environment Variables PATH.
  • macOS: Use Homebrew: brew install ffmpeg
  • Linux: Use your package manager: sudo apt install ffmpeg

Usage

CLI Tools

The package provides several CLI tools. If installed globally or as a dependency, you can use the commands directly. Otherwise, use npm run.

Convert to WAV

The base script maps tracker frames to emulator registers, rendering standard 44.1kHz 16-bit PCM Stereo WAV chunks directly to disk.

npm run convert -- [input_path] -o [output_dir]
# Or using the binary command:
fym-convert [input_path] -o [output_dir]

The script will batch convert everything from input/ to standard .wav files into the output/ directory. It naturally skips over existing files.

Custom Mixing Styles

You can override the YM/AY chip modes and ABC stereo panning:

fym-convert -s ay_bca -o ./custom_output ./custom_input
# For mono output:
fym-convert -m ./custom_input

Valid mixing styles are:

• ym_abc, ym_acb, ym_bac, ym_bca, ym_cab, ym_cba (Yamaha YM2149 chip)
• ay_abc, ay_acb, ay_bac, ay_bca, ay_cab, ay_cba (General Instrument AY-3-8910 chip)

The suffix defines the stereo panning for channels A, B, and C respectively:

• abc: A=10%, B=50%, C=90%
• acb: A=10%, B=90%, C=50%
• bac: A=50%, B=10%, C=90%
• bca: A=50%, B=90%, C=10%
• cab: A=90%, B=10%, C=50%
• cba: A=90%, B=50%, C=10%

Use -m or --mono to center all channels (50% panning) and use native mono emulation for improved performance.

(Defaults to ym_abc if not specified).

The script respects your stereo panning set up and will output your .wav files into specifically named folders, for example output/ay_bca/song.wav.

Batch Parallel Conversion (WAV)

You can process conversions for all 12 mixing styles in parallel:

fym-convert-all -o ./custom_output ./custom_input

This automatically generates folders for every mixing style in the output directory.

MP3 Compression

Once you have generated your .wav files, you can encode them to compressed 192kbps .mp3 format:

fym-convert-mp3 -o ./custom_mp3s ./custom_wavs

This script will:

• Search through the output/ directory for .wav files.
• Automatically mirror the directory structure to an output_mp3/ directory.
• Utilize all your CPU cores to run concurrent ffmpeg subprocesses.
• Skip over any existing .mp3 files to avoid redundant encoding.

Library Usage

This package can also be used as a library in other Node.js projects.

const fs = require("fs");
const { convertToWavBuffer } = require("fym_converter");

const fymData = fs.readFileSync("music.fym");
const wavBuffer = convertToWavBuffer(fymData, "music.fym", {
  mixingStyle: "ym_abc", // Optional
  sampleRate: 44100, // Optional
});

fs.writeFileSync("output.wav", wavBuffer);

Available Exports

• convertToWavBuffer(buffer, filename, options): Returns a complete WAV file as a Node.js Buffer.
• FYMReader: Low-level reader for .fym files.
• Ayumi: The core PSG emulation engine.
• parseMixingStyle(style): Utility to parse mixing strings.

Background

.fym files store precisely interleaved register dumps for AY chips dynamically compressed using zlib/deflate at roughly 50Hz. The conversion process automatically attempts to inflate the source file with zlib to handle these compressed streams, but it is designed to work seamlessly either way—automatically detecting if the data is already uncompressed. The scripts then feed these register dumps into the ayumi.js emulator and natively stitch exactly synced chunks back together directly as a byte stream, avoiding browser-based DOM interfaces entirely.

Credits and References

This project was built using the following tools and resources:

• AI Assistance: Developed with the help of Gemini 3.1 Pro and Flash.
• Audio Emulation:
  • ayumi.js adapter adapted from drale18/ayumi-js-regs.
  • fym.js adapted from lunar-sh/emu8910 and Turbo support added from ym.mmcm.ru.