View on GitHub

ym2151-log-editor

ym2151-log-editor

ym2151-log-editor

YM2151 Event Log Editor (TUI Interface). Written in Rust.

Japanese English

Status

Installation

cargo install --force --git https://github.com/cat2151/ym2151-log-editor

Overview

This is a terminal-based JSON editor for YM2151 synthesizer event logs. It assists with visualizing and editing YM2151 event data, with a particular focus on timing adjustment and event inspection.

Features

Quick Start

Installation

Rust 1.70 or later is required.

# Clone the repository
git clone https://github.com/cat2151/ym2151-log-editor.git
cd ym2151-log-editor

# Build
cargo build --release

# Run with a specified JSON file
cargo run -- path/to/your/file.json

Usage

# Launch the editor with a file
./target/release/ym2151-log-editor your_log.json

# Check for updates
./target/release/ym2151-log-editor check

# Update this application via cargo install
./target/release/ym2151-log-editor update

# If the filename is 'check' or 'update', specify it as a path to launch
./target/release/ym2151-log-editor ./check

Keyboard Shortcuts

Key Action
↑/↓ or k/j Move between events
PageUp / PageDown Jump 10 lines
Ctrl+U / Ctrl+D Jump 10 lines
[count]k / [count]j Move by count (vim style)
/ or ENTER Insert a new event before the current line
DELETE Delete the current event
0-9 Set wait time (0-9 milliseconds, cumulative mode only)
P Preview playback (play the entire JSON)
L Toggle loop playback (interactive mode)
T Toggle time display mode (Cumulative ↔ Timestamp)
S Save file
Q or ESC Exit application

JSON Format

The editor handles YM2151 event logs in the following JSON format:

{
  "events": [
    {
      "time": 0.0,
      "addr": "20",
      "data": "4F"
    },
    {
      "time": 0.01,
      "addr": "08",
      "data": "78"
    }
  ]
}

Time Display Modes

Cumulative Mode (Default)

Displays the wait time (delta) from the previous event. This is useful for editing timing, allowing you to check and adjust delays between events.

Example:

0.000000  20  4F    ← First event (time 0)
0.010000  40  16    ← 10ms after the previous event
0.010000  KeyON  78 ← 10ms after the previous event

Timestamp Mode

Displays the absolute time from the start. This is the internal format used when saving files.

Example:

0.000000  20  4F    ← 0ms from start
0.010000  40  16    ← 10ms from start
0.020000  KeyON  78 ← 20ms from start

Press the T key to switch between these modes.

KeyON Display

Events for register 0x08 (KeyON/KeyOFF register) are displayed as “KeyON” instead of “08” to improve readability:

0.010000  KeyON  78  ← Easily identify KeyON/KeyOFF events
0.500000  KeyON  00

Development

Project Structure

src/
├── main.rs       - Entry point and event loop
├── app.rs        - Application state and logic
├── models.rs     - Data structures (Ym2151Event, Ym2151Log)
└── ui.rs         - UI rendering

Build

cargo build          # Development build
cargo build --release # Optimized build

Testing

Sample test data is available in test_data/sample.json:

cargo run -- test_data/sample.json

Documentation

Refer to IMPLEMENTATION_PLAN.md for detailed implementation plans and future roadmap.

Dependencies

License

Refer to the LICENSE file for details.

Future Enhancements

For a complete roadmap, refer to IMPLEMENTATION_PLAN.md.

Project Goals

Out of Scope (Non-Goals)