osynic_midi 0.1.0

A MIDI -> keyboard mapper for the Osynic
Documentation

📖 关于项目

OsynicMIDI 是一个轻量级、高效的 MIDI 到键盘映射工具，使用 Rust 编写。它允许你用任何 MIDI 设备（如电子琴、鼓垫、MIDI 控制器）控制计算机上的键盘输入。

无论你是游戏玩家、音乐制作人，还是想要创意地使用 MIDI 设备，OsynicMIDI 都能为你提供简单而强大的解决方案。

为什么选择 OsynicMIDI？

✅ 简单易用 - 5秒快速启动，无需复杂配置
✅ 强大灵活 - 支持多种映射模式和自定义配置
✅ 现代界面 - 交互式菜单，使用箭头键和回车按钮
✅ 库 + CLI - 既可作为独立工具，也可嵌入你的 Rust 项目
✅ 可靠稳定 - 经过充分测试，生产就绪
✅ 开源免费 - MIT 许可，完全开源

⚡ 快速开始

1️⃣ 安装

cargo install osynic_midi

或从源码编译：

git clone https://github.com/osynicite/osynic_midi

cd osynic_midi

cargo build --release

2️⃣ 运行

osynic-midi start

3️⃣ 选择

用箭头键 ↑ ↓ 选择配置和设备，按 Enter 确认！

就这么简单！现在你可以用 MIDI 设备弹出键盘按键了 🎉

✨ 特性

🎹 MIDI 映射

  • 两种映射模式
    • 音符模式：每个 MIDI 音符映射到特定按键
    • 八度模式：按八度和音高自动映射

🎯 智能设备管理

  • 自动发现所有连接的 MIDI 设备
  • 基于设备名称的可靠连接（不依赖不稳定的索引）
  • 支持多个 MIDI 设备

⚙️ 灵活配置

  • JSON 格式的可读配置文件
  • 预设配置开箱即用
  • 易于创建自定义映射
  • 支持力度阈值过滤

🖥️ 现代化 CLI

  • 交互式菜单选择（类似 Vite）
  • 箭头键导航，直观易用
  • 支持非交互式模式用于脚本和自动化
  • 完整的命令行帮助系统

📚 全面文档

  • 完整的 API 文档
  • 详细的配置指南
  • 丰富的使用示例
  • 架构和设计文档

📦 安装

使用 Cargo（推荐）

cargo install osynic_midi

从源码编译

git clone https://github.com/osynicite/osynic_midi.git

cd osynic_midi

cargo build --release

编译后的二进制文件位于：

  • 开发版本：target/debug/osynic-midi.exe
  • 发布版本：target/release/osynic-midi.exe

系统要求

  • Rust：1.85.0 或更高版本
  • 操作系统：Windows、Linux 或 macOS
  • MIDI 设备：至少一个 MIDI 输入设备（可选，支持虚拟 MIDI 端口）

🚀 使用指南

基本命令

# 快速使用

osynic-midi


# 列出所有连接的 MIDI 设备

osynic-midi list-devices


# 列出所有可用的配置文件

osynic-midi list-configs


# 启动交互式 MIDI 映射

osynic-midi start


# 创建一个新的映射配置文件（交互式）

osynic-midi create


# 从本地文件加载配置文件

osynic-midi load-local


# 使用指定配置启动

osynic-midi start -c configs/my_config.json


# 指定映射模式（notes 或 octaves）

osynic-midi start -m notes


# 同时指定配置和模式（非交互式）

osynic-midi start -c configs/my_config.json -m notes


# 从本地路径加载配置和指定模式

osynic-midi load-local -c /path/to/config.json -m notes

交互式菜单

运行 osynic-midi start 后，你会看到三个选择菜单：

? Select configuration file:
❯ midi_config.json
  midi_config_10ka.json
  midi_config_10kab.json
  ...

操作方式：

  • ↑ / ↓ - 上下移动
  • Enter - 确认选择
  • Ctrl+C - 取消

工作流程

  1. 检查设备

    osynic-midi list-devices

    确保你的 MIDI 设备已识别

  2. 选择配置方式

    方式 A：使用现有配置（推荐新手）

    osynic-midi list-configs

osynic-midi start

    方式 B：创建新配置（推荐自定义）

    osynic-midi create

    按照提示逐步创建你的映射配置

    方式 C：加载本地配置文件

    osynic-midi load-local

    指定配置文件的完整路径（可以在任何位置）

  3. 启动映射

    osynic-midi start

    按照交互式提示完成设置

  4. 开始使用 现在你可以使用 MIDI 设备弹出键盘按键了！

📚 文档

完整文档位于 docs/ 目录：

文档 内容
快速开始 5分钟入门指南
CLI 完整指南 命令行工具的详细使用说明
库 API 文档 Rust 库的完整 API 参考
架构设计 项目结构和设计说明
配置指南 JSON 配置文件详细说明
更新日志 版本历史和更新内容
故障排除 常见问题和解决方案

💡 示例

示例 1：快速启动

osynic-midi start -c configs/midi_config.json -m notes

示例 2：库中使用

use osynic_midi::{Config, MappingMode, start_mapping};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 加载配置
    let config = Config::load("configs/midi_config.json")?;
    
    // 启动 MIDI 映射
    start_mapping(
        "configs/midi_config.json".to_string(),
        "X8III".to_string(),
        MappingMode::Notes,
    ).await?;
    
    Ok(())
}

详见 examples/ 目录获取更多示例。

🎯 使用场景

🎮 游戏玩家

  • 用 MIDI 键盘控制游戏（Osu!mania、节奏游戏等）
  • 创建专业游戏外设映射

🎵 音乐制作人

  • 用 MIDI 控制器控制 DAW
  • 创建自定义快捷键映射

💻 开发者

  • 作为库集成到 Rust 项目中
  • 创建专业的 MIDI 应用程序

🏠 爱好者

  • 创意使用 MIDI 设备
  • 自动化和控制应用程序

🔧 配置示例

Osu!Mania 风格

{
  "mapping_mode": "notes",
  "velocity_threshold": 1,
  "octaves": {},
  "note_mappings": {
    "36": "A", "37": "S", "38": "D", "39": "F",
    "40": "G", "41": "H", "42": "J", "43": "K"
  }
}

钢琴键盘式

{
  "mapping_mode": "octaves",
  "velocity_threshold": 0,
  "octaves": {
    "3": {
      "C": "A", "C#/Db": "W", "D": "S", "D#/Eb": "E",
      "E": "D", "F": "R", "F#/Gb": "F", "G": "T",
      "G#/Ab": "G", "A": "Y", "A#/Bb": "H", "B": "U"
    }
  },
  "note_mappings": {}
}

更多配置见 配置指南。

🤝 贡献

欢迎贡献！无论是下列哪一种方式，我们都很感谢：

  • 🐛 报告 Bug
  • 💡 提出新想法
  • 📝 改进文档
  • 🔧 提交代码修复

请通过 GitHub Issues 或 Pull Requests 与我们联系。

❓ 常见问题

Q: 支持哪些操作系统？

A: Windows、Linux 和 macOS 都支持。

Q: 可以不用 MIDI 设备使用吗？

A: 可以使用虚拟 MIDI 端口（如 Windows 的 loopMIDI）进行测试。

Q: 支持多个 MIDI 设备吗？

A: 目前一次只能使用一个设备，但可以快速切换。

Q: 如何创建自定义配置？

A: JSON 格式非常简单。参考 配置指南。

Q: 可以在脚本中使用吗？

A: 可以！使用 -c 和 -m 参数运行非交互式模式。

更多问题见 故障排除指南。

📊 项目状态

  • ✅ 稳定版本
  • ✅ 生产就绪
  • ✅ 完整文档
  • ✅ 活跃维护

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

感谢以下项目的支持：

📮 联系方式