ym2151-log-editor

YM2151 event log editor (TUI interface). Written in Rust.

Overview

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

Features

• JSON Visualization: Displays YM2151 event logs in a human-readable format
• KeyON Display: Displays events for register 0x08 as “KeyON” for better readability
• Time Display Modes: Toggles between cumulative time (wait) and absolute timestamps
  • Cumulative Mode: Shows delta time between events (convenient for editing)
  • Timestamp Mode: Shows absolute time from start (internal storage format)
• Navigation: Browse events using arrow keys
• File Operations: Load and save JSON files

Quick Start

Installation

Requires Rust 1.70 or later.

# 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 editor with a specified file
./target/release/ym2151-log-editor your_log.json

Keyboard Controls

Key	Action
↑/↓	Move between events
/ 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 (plays the entire JSON)
T	Toggle time display mode (Cumulative ↔ Timestamp)
S	Save file
Q or ESC	Exit application

JSON Format

The editor handles YM2151 event logs in JSON format:

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

• time: Absolute timestamp (in seconds)
• addr: YM2151 register address (hexadecimal)
• data: Register data value (hexadecimal)

Time Display Modes

Cumulative Mode (Default)

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

Example:

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

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 toggle 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/OFF 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 provided 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

• ratatui 0.29 - Terminal UI framework
• crossterm 0.29 - Terminal backend
• serde 1.0 - Serialization framework
• serde_json 1.0 - JSON support

Related Projects

• ym2151-tone-editor - YM2151 Tone Editor (Reference Implementation)
• ym2151-log-play-server - YM2151 Log Playback Server

License

See the LICENSE file for details.

Future Enhancements

• Editing register address and data value of inserted events
• Undo/redo functionality
• Audio preview integration
• Bulk time scaling
• Event filtering and searching

For a complete roadmap, refer to IMPLEMENTATION_PLAN.md.

Project Goals

• Minimum wait time editing
• Minimum event editing
• Minimum event visualization

Out of Scope (What the project does NOT aim for)

• Advanced features:
  • Event insertion via MML input.
  • Advanced visualization. Parallel display of 8 channels. Implementing all features and beyond found in DAW event editors.
  • DAW functionality. Piano roll display and editing. Staff notation display and editing. Data automation display and editing. Event insertion via MIDI IN.
  • Querying. Advanced editing achievable by querying events. Filtering and editing only notes, specific events, etc., and highly intelligent automatic event dependency recognition that preserves inter-event dependencies even when events are added or removed.
  • Decompilation. Analyzing event content and highly intelligent inverse transformation to SMF or MML. Calculating BPM, measure, beat, and tick from time with 100% success rate.

This site is open source. Improve this page.