OMP3 (Olfactory MP3 Prototype)

OMP3 是一个探索数字气味播放描述协议与软件模拟的个人想法与研究原型。

声明与项目边界
本项目纯属个人探索性研究原型，旨在定义与校验结构化的数字播放时间线协议。本项目目前完全没有实现真实气味记录、物理释放或气味重现能力，未来可能会根据研究进展继续开发。请勿将本项目理解为已完成的产品或具备实际气味播放能力的系统。

---

1. 项目定位与非目标 (Scope & Non-Goals)

本原型实现的内容

• 数据格式标准 (.omp3)：定义基于 JSON 的气味播放时间线描述规范，支持多通道编排、强度曲线与 ADSR 包络控制。
• 协议校验器 (Validator)：严格校验格式元数据、未知字段、数值边界、包络完整性、通道唯一性与安全防护限制。
• 软件播放模拟器 (Simulator)：纯软件模拟离散播放时间线事件（包含通道、瞬时强度、时间戳、包络状态），输出机器可读的事件流。
• 本地可视化播放器 (Visual Player)：纯标准库零外部依赖的本地 Web 服务器与交互式单页可视化播放器，支持文件加载校验、元数据与轨道包络展示、高精度时间线模拟与播放控制（播放/暂停/复位/进度拖拽与瞬时强度监视）。
• CLI 工具与测试套件：提供 validate、simulate 与 serve 命令行接口及完备自动化测试。

明确的非目标 (Non-Goals)

• 不记录与采样真实气味：不涉及电子鼻硬件接入、气敏传感器数据采集或色谱/质谱分析。
• 不驱动物理执行机构：不控制雾化喷头、风扇、加热阀门或微流控芯片。
• 不生成化学配方：不处理精油配比、香精分子合成或化学安全评定。
• 不声称重现气味：所有输出均为协议层与时间线状态的纯数字模拟。

---

2. .omp3 数据格式规范

首版 .omp3 为标准 JSON 文档，核心包含以下五个顶级节点：

{
  "format": "omp3",
  "version": "0.1.0",
  "metadata": {
    "title": "Cedar & Citrus Ambient Accord",
    "description": "A research prototype digital playback timeline. Does not record or reproduce physical odors.",
    "author": "Personal Research Project",
    "created_at": "2026-09-07T00:00:00Z",
    "tags": ["prototype", "ambient"]
  },
  "safety_guard": {
    "max_intensity": 1.0,
    "max_continuous_duration_ms": 10000,
    "min_interval_ms": 200,
    "max_total_channels": 16,
    "max_concurrent_channels": 4,
    "cooldown_ms": 1000
  },
  "tracks": [
    {
      "channel": 1,
      "name": "Simulated Sweet Orange Accord",
      "description": "Primary high-volatility mock channel",
      "start_time_ms": 0,
      "intensity": 0.8,
      "duration_ms": 3000,
      "envelope": {
        "attack_ms": 300,
        "decay_ms": 400,
        "sustain_level": 0.6,
        "release_ms": 500
      }
    }
  ]
}

字段说明

• format: 格式标识，必须为 "omp3"。
• version: 协议版本号（如 "0.1.0"）。
• metadata: 文件元信息，必须包含 title、description 和 author。
• safety_guard: 播放安全防线，所有限制数值禁止为负数：
  • max_intensity: 播放强度上限（范围 [0.0, 1.0]）。
  • max_continuous_duration_ms: 单轨连续播放时长上限（毫秒）。
  • min_interval_ms: 触发最小间隔（毫秒）。
  • max_total_channels: 允许的最大总通道数。
  • max_concurrent_channels: 最大并发激活通道数。
• tracks: 播放轨道列表：
  • channel: 通道标识符（正整数或非空字符串），同一文件内必须唯一。
  • intensity: 峰值强度（范围 [0.0, 1.0]，且不得超过 safety_guard.max_intensity）。
  • duration_ms: 播放总时长（必须大于 0，且满足包络覆盖条件）。
  • envelope: ADSR 包络参数：
    • attack_ms: 爬升阶段时长（毫秒，>= 0）。
    • decay_ms: 衰减阶段时长（毫秒，>= 0）。
    • sustain_level: 维持阶段强度比例（范围 [0.0, 1.0]）。
    • release_ms: 释放归零时长（毫秒，>= 0）。
    • 约束条件：duration_ms >= attack_ms + decay_ms + release_ms。

---

3. 快速上手 (Quick Start)

运行环境

• Python 3.11+
• 无第三方运行时依赖（核心协议与软件模拟仅使用 Python 标准库）。

本地安装准备 (Local Installation)

本项目采用标准 src 布局（src/omp3）。在全新的干净检出环境中，必须先在仓库根目录执行本地安装（如可编辑安装），以确保模块路径注册与 CLI 命令生效：

python -m pip install -e .

注意：本项目不声称在未经本地安装或未配置模块路径的情况下可直接导入 omp3 模块。执行上述安装后，方可直接通过 python -m omp3.cli 或安装生成的 omp3 命令执行后续操作。

验证 .omp3 文件

使用 validate 子命令校验输入文件，输出格式化 JSON：

python -m omp3.cli validate examples/demo.omp3.json
# 或直接使用安装好的 CLI 命令：
omp3 validate examples/demo.omp3.json

成功输出示例：

{
  "status": "valid",
  "file": "examples/demo.omp3.json",
  "format": "omp3",
  "version": "0.1.0",
  "metadata": { ... },
  "track_count": 2,
  "total_duration_ms": 4500,
  "channels": [1, 2],
  "warnings": []
}

软件时间线模拟

使用 simulate 子命令生成纯软件播放事件流：

python -m omp3.cli simulate examples/demo.omp3.json
# 或直接使用安装好的 CLI 命令：
omp3 simulate examples/demo.omp3.json

成功输出示例：

{
  "status": "success",
  "file": "examples/demo.omp3.json",
  "simulation": {
    "simulation_type": "software_mock",
    "safety_notice": "Pure software playback timeline simulation. No physical actuation or odor emission.",
    "total_duration_ms": 4500,
    "track_count": 2,
    "active_channels": [1, 2],
    "max_concurrent_active_channels": 2,
    "peak_intensity": 0.8,
    "events": [
      {
        "time_ms": 0,
        "channel": 1,
        "state": "ATTACK",
        "intensity": 0.0,
        "description": "Channel 1: Attack phase started (target 0.80)"
      },
      ...
    ]
  }
}

可选参数 --step-ms N 支持按固定毫秒步长采样瞬时强度曲线：

python -m omp3.cli simulate examples/demo.omp3.json --step-ms 200

本地可视化播放器 (Visual Player)

使用 serve 子命令启动完全无外部依赖的本地 Web 可视化播放器与模拟器：

# 启动播放器并预载示例文件（自动打开默认系统浏览器）：
python -m omp3.cli serve examples/demo.omp3.json

# 或直接使用安装好的 CLI 命令：
omp3 serve examples/demo.omp3.json

# 启动空播放器（可在浏览器页面中通过本地文件选择器或拖拽加载文件）：
python -m omp3.cli serve

可选参数：

• --host HOST: 监听的网络接口地址（默认 127.0.0.1）
• --port PORT: 监听端口（默认 8080）
• --no-browser: 禁止在服务启动时自动打开系统浏览器

安全与模拟器边界提醒
可视化播放器仅供纯软件模拟与视觉化展示，所有轨道包络、瞬时强度与时间线演进均为数字状态演算。严禁假定其具备真实气味记录、化学合成或物理喷发能力。

---

4. 自动化测试 (Testing)

项目采用 Python 标准库 unittest 编写完备测试套件，可直接运行：

python -m unittest discover -s tests -v

若环境中安装了 pytest，亦可直接使用：

pytest -v

测试套件完整覆盖：

• 基础模型构建与字典序列化/反序列化（Roundtrip）。
• 关键字段缺失、未知字段注入的强校验拦截。
• 越界强度、负数安全限制、单轨通道重复的错误处理。
• 包络时长覆盖不足（duration_ms < attack + decay + release）的拦截。
• 纯软件时间线模拟事件时序、状态转换与峰值聚合正确性。
• CLI 命令返回值、异常退出码与 JSON 输出格式契约。
• Web 可视化播放器 HTTP 基础路由、API 端点（/api/status、/api/document、/api/load、/api/evaluate、/api/validate、/api/reset）与安全边界（防目录穿越、方法校验、非法负载防崩溃）。
• CLI serve 子命令参数解析、非法文件路径与格式拦截及预加载容错性。

---

5. 未来探索方向 (Future Roadmap)

• 时钟与音画同步协议：研究基于 SMPTE / 毫秒级外部时间码的气味播放事件对齐协议。
• 气味通道描述映射库：探索通道编号与标准香调分类（如香味轮轮廓分类）的元数据挂载标准。
• 硬件抽象层（HAL）参考接口：定义安全、不可逆的硬件接口抽象层规范，用于未来概念硬件的防呆与防过载验证。