XiTune · API Reference

XiTune API 规范 v1.0

CLI · REST · Python SDK · XiMind 对接

文档编号：D2-P6-TECH-002 · 版本：v1.0 · 发布：2026-05-05

自动化友好 · 脚本即调音

4

API 接入方式

.xmeas

测量格式

gRPC

AI 云端

XiTune API 规范 v1.0

摘要

本文档定义 XiTune 对外的编程接口,包含 CLI 命令、Desktop REST 本地服务、Python SDK、XiMind 云端 API 四大接入方式,供 Tier1 调音工程师、主机厂集成团队、二次开发合作伙伴使用。

API 红线

.xmeas 文件必须签名 · 未签名文件 API 拒绝接受
云端 API 默认 TLS 1.3 + OAuth 2.0 · 不支持明文
Python SDK 所有破坏性变更提前 6 个月公告
AI 调用必须有离线降级路径

1. API 总览

1.1 四种接入方式

graph TB
    User[用户 / 脚本]
    User --> CLI[CLI 命令行]
    User --> SDK[Python SDK]
    User --> REST[Desktop REST<br/>localhost:54330]
    User --> GUI[XiTune App GUI]

    CLI --> Core[XiTune Core]
    SDK --> Core
    REST --> Core
    GUI --> Core

    Core --> Cloud[XiMind 云端 API]

    class User xyL4
    class CLI,SDK,REST,GUI xyL3
    class Core xyL2
    class Cloud xyL5

1.2 典型用法矩阵

用法	CLI	SDK	REST	GUI
交互式调音	❌	部分	部分	✅ 首选
批量产线调音	✅ 首选	✅	✅	❌
CI 回归测试	✅	✅	部分	❌
自定义分析流水线	✅	✅ 首选	❌	❌
与 MES / PLM 集成	部分	✅	✅ 首选	❌

2. CLI 接口

2.1 主命令

xitune --help
# 子命令: measure | analyze | tune | report | project | cloud | version

2.2 常用命令

# 1. 启动测量
xitune measure \
  --config measure.xicfg \
  --vehicle "bmw-3-series-2024" \
  --output session.xmeas

# 2. 分析
xitune analyze \
  --input session.xmeas \
  --output result.xanalyze \
  --metrics freq,phase,thd,rt60

# 3. AI 辅助调音
xitune tune \
  --input session.xmeas \
  --mode assist \
  --target "natural" \
  --output params.xiparam

# 4. 生成报告
xitune report \
  --input result.xanalyze params.xiparam \
  --template standard \
  --out report.pdf

# 5. 批量模式(产线)
xitune project run --config project.yaml

2.3 配置文件 `measure.xicfg`

version: 1
vehicle:
  class: midsize-sedan
  amp: XiAmp-Pro-8
  dsp: XiDSP-D2
mics:
  - { id: 1, position: "FL", mic_serial: "XM-001" }
  - { id: 2, position: "FR", mic_serial: "XM-002" }
  - { id: 3, position: "DriverEarL", mic_serial: "XM-003" }
  - { id: 4, position: "DriverEarR", mic_serial: "XM-004" }
  # ...
signal:
  type: exponential_sweep
  start_hz: 20
  end_hz: 20000
  duration_s: 8
conditions:
  - { label: static, weight: 0.7 }
  - { label: 60kmh, weight: 0.3 }
privacy:
  upload_raw_audio: false

2.4 退出码

code	含义
0	成功
1	通用错误
2	参数错误
3	硬件未连接
4	签名 / 授权失败
5	云端不可达(未启用离线模式时)
6	测量数据异常(SNR 过低 / 通道丢失)

3. Python SDK

3.1 安装

pip install xitune-sdk
# 或通过官方离线安装包(air-gapped 客户)

3.2 快速上手

from xitune import XiTuneClient, MeasureConfig

client = XiTuneClient()

# 1. 测量
cfg = MeasureConfig.load("measure.xicfg")
session = client.measure(cfg, output="session.xmeas")

# 2. 分析
result = client.analyze(session, metrics=["freq", "phase", "thd"])

# 3. AI 辅助
params = client.tune(
    session=session,
    mode="assist",
    target="natural",
)

# 4. 生成报告
client.report(result, params, out="report.pdf", template="standard")

3.3 SDK 核心 API

方法	说明
`XiTuneClient()`	客户端初始化(读取许可)
`.measure(config, output)`	触发测量
`.analyze(session, metrics)`	分析已有 session
`.tune(session, mode, target)`	AI 建议调音参数
`.report(result, params, out)`	生成 PDF
`.project.run(config)`	项目批量
`.cloud.login(token)`	云端登录
`.cloud.upload(session)`	上传到归档
`.events.on("measurement_done")`	事件回调

3.4 事件订阅

@client.events.on("measurement_progress")
def on_progress(pct):
    print(f"进度: {pct}%")

@client.events.on("channel_error")
def on_err(ch, reason):
    print(f"通道 {ch} 异常: {reason}")

4. Desktop REST API

4.1 本地服务

XiTune Desktop 启动后在 http://127.0.0.1:54330 暴露 REST:

仅监听环回,外网不可达
Bearer Token 认证(GUI 生成,用户复制)
默认关闭,需在设置中启用

4.2 主要端点

方法	路径	用途
GET	`/v1/status`	服务状态 / 硬件状态
POST	`/v1/measure/start`	启动测量
GET	`/v1/measure/{id}`	测量进度 / 结果
POST	`/v1/analyze`	触发分析
POST	`/v1/tune`	AI 调音
POST	`/v1/report`	生成 PDF
GET	`/v1/devices`	已连接的 XiMic / XiCal 列表

4.3 启动测量示例

POST /v1/measure/start
Authorization: Bearer xtk-xxx
Content-Type: application/json

{
  "config_path": "C:/proj/measure.xicfg",
  "vehicle_id": "bmw-3-2024",
  "output": "C:/proj/session.xmeas"
}

响应:

{
  "measure_id": "m-20261215-001",
  "status": "running",
  "estimated_seconds": 60
}

5. 云端 API(对接 XiMind)

5.1 架构

graph LR
    XiTune[XiTune 客户端]
    Gateway[XiMind 网关]
    Infer[XiMind 推理]
    Archive[归档存储]

    XiTune -->|gRPC + TLS| Gateway
    Gateway --> Infer
    Gateway --> Archive

    class XiTune xyL3
    class Gateway,Archive xyL4
    class Infer xyL5

5.2 关键端点

Endpoint	方法	用途
`/v1/tune/analyze`	POST	上传摘要请求 AI 分析
`/v1/tune/recommend`	POST	请求调音参数建议
`/v1/tune/feedback`	POST	上传人工最终参数(训练)
`/v1/tune/presets/{class}`	GET	车型级别预设
`/v1/archive/upload`	POST	上传 session(归档)
`/v1/archive/list`	GET	客户项目列表

5.3 请求示例(Protobuf/JSON 混用)

POST /v1/tune/recommend
Authorization: Bearer <OAuth Token>

{
  "meas_hash": "sha256:abc...",
  "meas_summary": { "bands": [...], "thd": [...] },
  "vehicle": {
    "class": "midsize-sedan",
    "amp_model": "XiAmp-Pro-8",
    "dsp_model": "XiDSP-D2"
  },
  "target_curve": "natural",
  "privacy": { "upload_raw_audio": false }
}

响应:

{
  "session_id": "aisrv-x1",
  "params": {
    "eq": [...],
    "drc": [...],
    "delay": [...]
  },
  "confidence": 0.87,
  "notes": "Recommended based on 2k similar vehicles.",
  "latency_ms": 3820
}

5.4 SLA

可用性:99.5%
P50 延时:≤ 3s · P99 延时:≤ 8s
连续 3 次 5xx 错误自动熔断 · 客户端切离线

6. `.xmeas` / `.xanalyze` / `.xiparam` 文件格式

6.1 `.xmeas` 二进制结构

见 spec.md §4.1。Python SDK 提供 xitune.formats.XmeasFile.load(path) 解析。

6.2 `.xanalyze` JSON 结构(摘要)

{
  "version": 1,
  "source_meas_hash": "sha256:abc...",
  "channels": [
    {
      "id": 1,
      "position": "FL",
      "freq_response": [...],
      "phase": [...],
      "thd_by_freq": [...]
    }
  ],
  "soundfield_consistency": 0.82,
  "mushra_predicted": 85.3
}

6.3 `.xiparam` 调音参数

{
  "version": 1,
  "target_hw": "XiAmp-Pro-8",
  "eq_bands": [
    { "ch": 0, "fc": 80, "gain_db": -3, "q": 1.2, "type": "peak" }
  ],
  "drc": { "threshold_db": -24, "ratio": 2.5, "attack_ms": 5, "release_ms": 100 },
  "delay_ms": [0.0, 0.5, 1.2, 1.2, 0.5, 0.0, 0.3, 0.3]
}

7. XiStudio 插件 API

7.1 插件信息

XiTune 作为 .xiplugin 在 XiStudio Pro+ 运行,暴露扩展点:

扩展点	用途
`panel.right.xitune`	侧边栏面板
`workflow.xitune.measure`	工具栏快捷"测量"
`workflow.xitune.tune`	工具栏快捷"AI 调音"
`workflow.xitune.report`	工具栏快捷"生成报告"

7.2 项目文件共享

.xiproj 新增字段 xitune_sessions: []
XiTune 测量结果自动关联到当前 XiStudio 项目
调音参数回填流图节点时保留"由 XiTune 生成"标记

8. 错误码与诊断

8.1 通用错误码

code	含义	处置
4001	硬件未连接	检查 USB / 电源
4002	通道校准异常	重新执行 94dB 校准
4003	跨通道抖动超限	检查时钟源 / 更换线缆
4101	签名失败	重新生成 `.xmeas`
4201	云端不可达	切离线或检查网络
4202	OAuth Token 过期	重新登录
4301	许可证过期	联系销售续订

8.2 日志

GUI: 菜单 → 工具 → 日志查看器
CLI: xitune --log-level debug ...
SDK: Python logging · 默认级别 INFO

9. 版本兼容性

9.1 语义化版本

主版本(1.x → 2.0):破坏性变更 · 6 月公告
次版本(1.0 → 1.1):新增方法 · 向后兼容
补丁(1.0.0 → 1.0.1):Bug 修复 · 完全兼容

9.2 废弃策略

@deprecated 标记后保留 ≥ 12 个月
废弃方法返回字段 deprecated: true

10. 附录

10.1 关联文档

10.2 外部标准

gRPC / Protobuf 3
OAuth 2.0 / TLS 1.3
REST / JSON Schema
Python 3.10+ / Rust 2021

10.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · CLI + SDK + REST + XiMind API

api.md · D2-P6-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 平台软件团队

XiTune API 规范 v1.0

XiTune API 规范 v1.0

1. API 总览

1.1 四种接入方式

1.2 典型用法矩阵

2. CLI 接口

2.1 主命令

2.2 常用命令

2.3 配置文件 measure.xicfg

2.4 退出码

3. Python SDK

3.1 安装

3.2 快速上手

3.3 SDK 核心 API

3.4 事件订阅

4. Desktop REST API

4.1 本地服务

4.2 主要端点

4.3 启动测量示例

5. 云端 API(对接 XiMind)

5.1 架构

5.2 关键端点

5.3 请求示例(Protobuf/JSON 混用)

5.4 SLA

6. .xmeas / .xanalyze / .xiparam 文件格式

6.1 .xmeas 二进制结构

6.2 .xanalyze JSON 结构(摘要)

6.3 .xiparam 调音参数

7. XiStudio 插件 API

7.1 插件信息

7.2 项目文件共享

8. 错误码与诊断

8.1 通用错误码

8.2 日志

9. 版本兼容性

9.1 语义化版本

9.2 废弃策略

10. 附录

10.1 关联文档

10.2 外部标准

10.3 版本历史

2.3 配置文件 `measure.xicfg`

6. `.xmeas` / `.xanalyze` / `.xiparam` 文件格式

6.1 `.xmeas` 二进制结构

6.2 `.xanalyze` JSON 结构(摘要)

6.3 `.xiparam` 调音参数