Bitphase

Bitphase

A modern web-based chiptune tracker designed for creating music on retro sound chips. Currently supports the AY-3-8910 / YM2149F chip (used in ZX Spectrum and other 8-bit computers), with plans to support additional chips in the future.

Features

Tracking

• Canvas-based pattern editor with order list
• Field-based editing with selection, copy/cut/paste, and magic paste
• Virtual channels — map multiple pattern columns onto a single hardware channel
• Transpose, increment/decrement, and channel swap editing tools
• Auto envelope and envelope-as-note modes
• Customizable keybindings

Instruments and tables

• AY/YM instrument editor with tone, noise, envelope, and sample playback
• Timer effects (waveform, PWM, and related AY timer instruments)
• Tables (known as Ornaments in Vortex Tracker 2)
• Built-in instrument presets
• Instrument preview playground

Playback

• Play, pause, play from cursor, play pattern, and solo/mute controls
• Real-time channel oscilloscopes
• MIDI keyboard input for note entry

Project I/O

• Open and save Bitphase projects (.btp)
• Import Pro Tracker 3 (.pt3) and Vortex Tracker 2 (.vt2) modules
• Export WAV, PSG, TMR, and SNDH (not supporting timer effects yet)
• Multi-chip PSG and TMR export as ZIP
• Command-line .btp to WAV export (pnpm btp-to-wav)

Workflow

• Undo/redo with labeled history
• Lua user scripts for batch edits on selections
• Automatic project backup with recovery on reload
• Custom themes and appearance settings

Prerequisites

• Node.js (v18 or higher; v20 recommended)
• pnpm (v10.11.0 or higher)
• Emscripten SDK — required for building the Ayumi WebAssembly module
• Git submodules — the Ayumi emulator lives in external/ayumi

Installing Emscripten

1. Download and install Emscripten from emscripten.org
2. Set the EMSDK environment variable to point to your Emscripten installation
3. Ensure emcc is available in your PATH

Getting Started

1. Clone the repository

   git clone --recurse-submodules https://github.com/paator/bitphase.git
   cd bitphase

   If you already cloned without submodules:

   git submodule update --init --recursive

2. Install dependencies

   pnpm install

3. Build WebAssembly modules

   pnpm build:wasm

   This compiles the Ayumi chip emulator to public/ayumi.wasm. Run this once after cloning, or whenever the WASM source changes.

4. Start the development server

   pnpm dev

5. Open your browser

   Navigate to http://localhost:5173 (or the port shown in the terminal)

Available Scripts

• pnpm dev — build WASM and start the development server with hot module replacement
• pnpm build — build WASM and create a production build
• pnpm build:wasm — build only the WebAssembly modules
• pnpm preview — preview the production build locally
• pnpm check — run TypeScript and Svelte type checking
• pnpm test — run tests in watch mode
• pnpm test:run — run tests once
• pnpm btp-to-wav — export a .btp project to WAV from the command line

Project Structure

bitphase/
├── cli/                     # Command-line tools (btp-to-wav, BTP loading)
├── docs/                    # Format documentation (e.g. TMR spec)
├── external/
│   └── ayumi/               # AY-8910 emulator C source (git submodule)
├── public/                  # Static assets and runtime audio code
│   ├── ayumi.wasm           # Compiled chip emulator
│   ├── bitphase-audio-processor.js
│   ├── tracker-*.js         # AudioWorklet tracker pipeline
│   ├── ay-*.js              # AY chip audio runtime
│   ├── fonts/
│   └── worklet/
├── src/
│   ├── app.css              # Global styles
│   ├── main.ts              # App entry point
│   ├── App.svelte           # Root component
│   ├── demo/                # Bundled demo songs (.btp)
│   ├── presets/             # Built-in instrument preset JSON files
│   └── lib/
│       ├── chips/           # Chip implementations and registry
│       │   ├── ay/          # AY-8910 (schema, adapter, renderer, processor)
│       │   └── base/        # Shared chip interfaces
│       ├── components/      # Svelte UI components
│       │   ├── AppLayout/
│       │   ├── Menu/
│       │   ├── Song/        # Pattern editor and song view
│       │   ├── Instruments/
│       │   ├── Modal/
│       │   ├── Settings/
│       │   ├── Tables/
│       │   ├── Theme/
│       │   ├── History/
│       │   ├── Details/
│       │   ├── Audio/
│       │   └── ...          # Shared UI primitives (Button, Input, etc.)
│       ├── config/          # Menu, keybindings, settings, themes, export formats
│       ├── models/          # Domain models (project, song, history, virtual channels)
│       │   ├── pt3/         # PT3 tuning tables
│       │   └── song/        # Song model utilities
│       ├── presets/         # Preset loading utilities
│       ├── services/        # Business logic
│       │   ├── app/         # Menu actions and app context
│       │   ├── audio/       # Playback and AudioWorklet bridge
│       │   ├── backup/      # Autobackup
│       │   ├── file/        # Import/export (BTP, PT3, VT2, WAV, PSG, TMR, SNDH)
│       │   ├── history/     # Undo/redo diff tracking
│       │   ├── midi/        # MIDI input
│       │   ├── modal/
│       │   ├── pattern/     # Pattern editing, navigation, clipboard
│       │   │   └── editing/ # Field-based editing strategies
│       │   ├── project/     # Project management and migration
│       │   ├── theme/
│       │   └── user-scripts/  # Lua user scripts
│       ├── stores/          # Reactive state (Svelte 5 runes, .svelte.ts)
│       ├── types/
│       ├── ui-rendering/    # Canvas-based pattern editor and order list
│       └── utils/
└── tests/                   # Tests mirroring src/ structure
    ├── fixtures/
    ├── lib/
    ├── public/              # Tests for public/ runtime scripts
    └── psg/

Documentation

• TMR format spec — Bitphase timer companion format for PSG export. In development!