🎹 OverField Music Player

Automated Piano & Guitar Player for "OverField"

🇺🇸 English  |  🇻🇳 Tiếng Việt  |  🇨🇳 简体中文  |  🇯🇵 日本語  |  🇮🇩 Bahasa Indonesia

Note

⚠️ Game Version Notice The musical furniture is currently only available in the Chinese server of "OverField" (开放空间). You can download it here: Bilibili Game Download

---

📖 Table of Contents

• Introduction
• Key Features
• Installation
• Usage Guide
• Controls & Hotkeys
• Configuration
• Song Format

---

🌟 Introduction

OverField Music Player is a high-precision automation script designed to play complex musical arrangements in the game OverField. It fully supports Piano and Electric Guitar (which share the same key layout). Built with AutoHotkey v2, it bridges the gap between MIDI compositions and in-game performance, offering millisecond-accurate timing and a suite of real-time controls.

Tip

Enjoying the tool? Please consider giving this project a ⭐ Star on GitHub to support development!

✨ Key Features

Feature	Description
🎯 Precision Timing	Uses timeBeginPeriod(1) and hybrid wait loops for accurate note execution.
📂 Music Library	Built-in playlist manager to organize .json song files.
🎛️ Live Control	Adjust Speed (10-500%), Transpose, and Seek in real-time.
🎹 MIDI Import	New! Convert .mid files to JSON directly via built-in API (Beta).
🔁 Loop Mode	New! Repeat the current song automatically.
🧠 Smart Logic	Auto-Pause on Alt-Tab, Optimization Mode for heavy songs.
🎹 Advanced Play	Sustain support and Mono Mode for cleaner melodies.

🚀 Installation

1. Install AutoHotkey v2: Download from autohotkey.com.
2. Download Script: Clone this repo or download the source.
3. Setup Directory: Ensure a Songs folder exists next to script.ahk (it creates one automatically).
4. Add Music: Drop your .json song files into the Songs folder.

🎮 Usage Guide

1. Run script.ahk (Right-click > Run Script).
2. Select a track from the Library list.
3. Choose the Target Window (your game window) from the dropdown.
4. Press Start or F4.

Tip

Use the (Unlocked - Any Window) option to test playback in a text editor like Notepad before playing in-game!

🎹 Controls & Hotkeys

Keyboard Shortcuts

Key	Action
F4	Toggle Play / Pause
F8	Stop Playback
Ctrl + →	Next Song
Ctrl + ←	Previous Song

Interface Controls

• Seeking: Drag the progress slider to jump to any point.
• Speed: Enter a percentage (e.g., 120 for 1.2x speed) or use Up/Down arrows.
• Playlist: Use ▲ / ▼ buttons to reorder songs.
• Navigation: Use Next / Prev buttons to change songs.

⚙️ Configuration

Settings are auto-saved to config.ini:

• Sustain: Keeps keys pressed for the duration of the note.
• No Chords: Ignores lower-octave keys (z, x, c...) usually used for chords.
• Mono Mode: Plays only one note at a time (highest priority).
• Auto-Next: Automatically plays the next song in the library.
• Loop: Automatically replays the current song when it ends.
• Max Polyphony: Limits simultaneous scrypt key presses.

📁 Song Format

The script accepts specific JSON structure. Example:

Click to view JSON Example

{
  "tracks": [
    {
      "instrument": { "family": "piano" },
      "notes": [
        {
          "time": 0.0,
          "duration": 0.5,
          "midi": 60
        }
      ]
    }
  ]
}

How to Convert MIDI to JSON

You have two ways to get your songs ready:

Method 1: Built-in Importer (Recommended)

1. Click the 🎹 Import MIDI (Beta) button in the script.
2. Select your .mid or .midi file.
3. The script will automatically convert it via API and ask if you want to save it to your library.

Method 2: Manual Web Conversion

If the built-in importer is down, you can still use the Tone.js MIDI tool:

1. Go to https://tonejs.github.io/Midi/.
2. Drag and drop your MIDI file onto the page.
3. Copy the generated JSON output.
4. Paste it into a new file in the Songs folder (e.g., mysong.json).

Tip

Need MIDI files? You can find high-quality MIDI sequences at OnlineSequencer.net.

Important

🎹 MIDI Selection Guide The in-game instrument is limited to 21 diatonic keys (3 octaves of white keys only) and 7 chord keys.

• Melody Range: C3 - B5 (White keys only).
• Chord Range: C2 - B2.
• Tip: For best results, choose songs with simple melodies (few sharps/flats) or transpose your MIDI to C Major or A Minor before converting.

📝 To-Do / Roadmap

• Direct MIDI Support: Built-in MIDI to JSON converter API (Beta).
• Custom Keybinding: Allow users to map MIDI notes to custom keys via UI.
• Theme Support: Dark mode and custom color schemes for the definition.
• Visual Overlay: A visual piano overlay to see which keys are being pressed.
• Data Recorder: Record in-game performance and save to JSON.
• Mini Mode: Compact UI for better visibility.

🤝 Contributing

Contributions are always welcome! This project is new and open to improvements. If you have any ideas, bug fixes, or new features (like better MIDI parsing!), please feel free to:

1. Fork the repository.
2. Create your feature branch.
3. Commit your changes.
4. Open a Pull Request.

---

📞 Contact & Support

If you have any questions or just want to hang out, reach out to me:

---

Created with ❤️ for the OverField Community