跳转至
DRAFT

格式 Demo · 套 0 · 现有 Xiyin 风格

本 demo 的定位

  • 基线:这是「现有」的 1 套——基于 xiyin-brand.css + xiyin-extra.css + xiyin-patch.css 三层 CSS 直出,不写任何自定义样式
  • 正文主题:虚拟产品 XiStudio Source 模块运行 demo (DSP 音频源模块)
  • 覆盖元素:H1-H6 / 列表 / 表格 / 12 类 admonition / 8 种代码语言 / 6 种 mermaid 图 / 数学公式 / Tabs / 脚注 / 缩写 / 定义列表 / emoji 全部展示
  • 对比对象:套 A(Stripe 风)、套 B(Linear/GitHub 风)、套 C(Notion/Apple 风)

1. 标题层级

1.1 H3 子节标题

H3 在现有规则下:左 3px 玫瑰金竖条 + 顶部 2px 三色细线 + 浅金渐变左晕染。

1.1.1 H4 细分

H4 用古铜金色,字重 700。

1.1.1.1 H5 细分(罕用)

H5 通常出现在长技术文档的最深层。

1.1.1.1.1 H6 细分(几乎不用)

H6 仅作完备性占位。

2. 段落与文本强调

XiStudio Source 模块负责从 音频设备 / 测试音 / WAV 文件 三类输入源 统一抽象 为采样块流。我们通过 device_id 参数路由到具体 SourceImpl 实现,使用 极光青 主题的 mermaid 图描绘信号链路。

行内代码示例:device_id=2 source_module.h:42 --no-pager。

键盘按键:按 Ctrl+Shift+P 调出命令面板,然后输入 Cmd+K Cmd+S 触发快捷键面板。

数学公式上下标:H2O 与 E=mc2,标记 重要术语,删除 过时方案。

3. 列表

3.1 无序列表(嵌套)

  • Source 模块的三种输入类型
    • Device · 物理音频设备(WASAPI / ASIO)
      • WASAPI loopback 用于系统音频抓取
      • WASAPI capture 用于麦克风录入
    • Tone · 测试音生成器(正弦 / 方波 / 白噪 / 粉噪)
    • WAV · 文件回放器(支持 16/24/32-bit)

3.2 有序列表

  1. 用户在 XiStudio 拖入 Source 节点
  2. 前端发 WebSocket source.create 请求
  3. 后端创建 SourceModule 实例
  4. DSP 引擎在下次 tick 时拉取首帧采样

3.3 任务清单

  • Source 模块 P0 完成(device + tone + wav)
  • 试点迁移 6 commit 落地
  • Sink 模块 P0 待启动
  • 端到端联调测试

3.4 定义列表

XiStudio
羲音工坊 · L4 开发工具层 · 可视化 DSP 算法 IDE
XiDSP
羲音芯 · L0 芯片基础层 · 车规级音频 DSP
Source 模块
音频源抽象 · 统一 device / tone / wav 三类输入

4. 引用 blockquote

单层引用:Source 模块的设计哲学是 「让上游算法看不见数据来自哪里」。 上游只关心采样块流,不关心信号源是真实麦克风还是合成正弦波。

多层嵌套:

二级引用:这是行业 DSP 框架的通行做法(JUCE、AudioKit、SuperCollider 都遵循)。

三级引用:Apple Core Audio 的 AudioUnit 抽象走得更远——把 source 和 sink 合并为统一的 IO 端口。

5. 表格(基础 / 对齐 / 长内容 / emoji 头)

5.1 三对齐示范

字段(左对齐) 类型(居中) 默认值(右对齐)
device_id int 0
sample_rate int 48000
frame_size int 256
bit_depth enum 32
loopback bool false

5.2 emoji 头 + 长内容

🎯 模块 🏷 SKU 📊 采样率支持 📝 备注
Source · Device src.dev.v1 16k / 44.1k / 48k / 96k / 192k 依赖 OS 驱动,WASAPI 在 Windows 11 24H2 上有时延抖动
Source · Tone src.tone.v1 任意(由 DSP 引擎决定) 内置 4 种波形 + 2 种噪声,FM 调制待 P1
Source · WAV src.wav.v1 16/24/32-bit · 任意通道数 大文件流式读取,不全部载入内存

6. Admonition 全 12 类

note · 普通笔记

Source 模块的实例由 SourceFactory::create() 创建,所有实例共享同一个 audio_clock。

info · 信息补充

WASAPI loopback 在 Windows 11 24H2 之前的版本有 ~2ms 时延抖动,P1 已通过 ring buffer 缓解。

tip · 最佳实践

在 dev 环境用 tone 源做端到端测试比 device 源更稳定 —— 没有外部硬件依赖,可重现。

success · 已通过验收

P0.5 试点的 6 commit 全部 mkdocs build 通过,103 个 warning 已分类沉淀(详见迁移报告)。

warning · 注意事项

切换 device_id 时如果当前流正在跑,会丢一帧——上层需要处理 SourceSwitched 事件做平滑。

danger · 严重警告

不要在 RT 线程内调用 device_enumerate(),会触发 COM 初始化阻塞,直接导致音频丢帧。

example · 示例代码

以下是创建一个 1kHz 正弦音源并跑 100ms 的最小示例: 

auto src = SourceFactory::create(SourceType::Tone);
src->set_param("freq", 1000.0f);
src->set_param("amp", 0.5f);
src->start();
std::this_thread::sleep_for(100ms);
src->stop();

abstract · 摘要

本文档的 H2-1 / H2-2 / H2-3 涵盖 Source 模块的运行时模型、API 契约、性能基线。

quote · 引言

"From Silicon to Sound" — 从芯片到声音,是 Xisound 的核心命题。

failure · 失败案例

早期版本的 WAV 源在大于 2GB 文件时会内存溢出,P0.5 修复后改为 mmap 流式读取。

bug · 已知问题

BUG-2026-042 · WASAPI loopback 在某些 Realtek 驱动下首次拉流会返回静音帧,workaround 是 prepad 1 帧静音。

question · 待回答

是否要支持 ASIO?当前 Windows 端只走 WASAPI,Tier-1 客户(车厂)生产环境也都是 WASAPI,ASIO 优先级 P3。

6.1 折叠 details(open / closed)

默认折叠 · 点击展开 · Source 模块的内部状态机 
states: { Idle, Preparing, Running, Pausing, Paused, Stopping, Stopped, Error }
transitions:
  Idle → Preparing : prepare()
  Preparing → Running : start()
  Running → Pausing : pause()
  Pausing → Paused : (auto)
  Paused → Running : resume()
  Running → Stopping : stop()
  Stopping → Stopped : (auto)
  ANY → Error : on_error
默认展开 · 性能基线 (Intel i7-12700H · Windows 11 24H2)
配置 单帧 CPU% 内存峰值
tone @ 48k/256 0.08% 1.2 MB
wav @ 48k/256 0.15% 8.4 MB
device @ 48k/256 0.32% 2.1 MB(含 WASAPI driver)

7. 代码块(8 种语言 + 行号 + 高亮 + 注解)

7.1 Python(无行号)

import xistudio as xs

src = xs.Source.tone(freq=1000.0, amp=0.5)
src.start()

7.2 C(行号 + 高亮第 4 行)

1
2
3
4
5
#include <xistudio/source.h>

source_t* src = source_create(SOURCE_TYPE_TONE);
source_set_param(src, "freq", 1000.0f);  // (1)!
source_start(src);
  1. 这是 Material 的 代码注解,鼠标悬停显示。

7.3 TypeScript

import { Source, SourceType } from '@xisound/xistudio'

const src = new Source(SourceType.Tone)
await src.setParam('freq', 1000)
await src.start()

7.4 Bash

# 启动 Xistudio dev 服务
cd AlgoDepartment/06_docs/site-build
python -m mkdocs serve --dev-addr 127.0.0.1:8765

7.5 PowerShell

# Windows 上 PowerShell 注意 $ 吞噬,要用单引号
$env:XISTUDIO_LOG_LEVEL = 'debug'
python -m mkdocs build --clean

7.6 YAML

source:
  id: src-001
  type: tone
  params:
    freq: 1000.0
    amp: 0.5
    waveform: sine
  routing:
    - to: mixer-1.in.0

7.7 JSON

{
  "source": {
    "id": "src-001",
    "type": "tone",
    "params": { "freq": 1000.0, "amp": 0.5, "waveform": "sine" },
    "routing": [{ "to": "mixer-1.in.0" }]
  }
}

7.8 Diff(代码变更)

- src->set_param("freq", 1000);
+ src->set_param("freq", 1000.0f);  // 必须用 float,int 会被静默截断

8. Tabs 切换

8.1 代码 Tabs(同一接口的 4 种语言实现)

src = xs.Source.tone(freq=1000.0)
src.start()

const src = new Source(SourceType.Tone)
await src.setParam('freq', 1000)
await src.start()

source_t* src = source_create(SOURCE_TYPE_TONE);
source_set_param(src, "freq", 1000.0f);
source_start(src);

var src = SourceFactory.Create(SourceType.Tone);
src.SetParam("freq", 1000.0f);
src.Start();

8.2 内容 Tabs(平台差异)

使用 WASAPI(loopback / capture)。需要 Windows 10 1903+。

使用 Core Audio(AudioUnit AUHAL)。所有 macOS 11+ 系统支持。

使用 ALSA / PulseAudio / PipeWire。推荐 PipeWire(Ubuntu 22.04+ 默认)。

使用 AVAudioEngine。session category 设为 playAndRecord。

9. Mermaid 图(全 6 类)

9.1 Flowchart 简单版

graph LR
    A[Device 输入] --> B[Source 模块]
    C[Tone 生成] --> B
    D[WAV 文件] --> B
    B --> E[DSP Pipeline]
    E --> F[Sink 输出]

    class A,C,D xyL1
    class B,E xyL3
    class F xyL0
L0 芯片 L1 硬件/输入 L3 算法

9.2 Flowchart 含 subgraph 子图(多层架构)

flowchart TB
    subgraph SG1["L1 · 信号输入层"]
        Dev["Device IO"]
        Tone["Tone Gen"]
        Wav["WAV Reader"]
    end

    subgraph SG3["L3 · 算法引擎层"]
        Src["SourceModule"]
        Mix["Mixer"]
        Eq["EQ"]
    end

    subgraph SG4["L4 · 工具层"]
        IDE["XiStudio IDE"]
    end

    Dev --> Src
    Tone --> Src
    Wav --> Src
    Src --> Mix --> Eq
    IDE -.config.-> Src
    IDE -.config.-> Mix

    class SG1 xySgL1
    class SG3 xySgL3
    class SG4 xySgL4
    class Dev,Tone,Wav xyL1
    class Src,Mix,Eq xyL3
    class IDE xyL4

9.3 sequenceDiagram 时序图

sequenceDiagram
    autonumber
    participant U as User (XiStudio)
    participant F as Frontend (Vue 3)
    participant B as Backend (C#)
    participant D as DSP Engine

    U->>F: 拖入 Source 节点
    F->>B: WS source.create {type: tone}
    B->>D: create_source(TONE)
    D-->>B: source_id=42
    B-->>F: { id: 42, status: idle }
    F->>B: WS source.start {id: 42}
    B->>D: start(42)
    D-->>B: started
    B-->>F: { status: running }
    F->>U: ✓ Source 已运行

9.4 classDiagram 类图

classDiagram
    class ISource {
        <<interface>>
        +start() void
        +stop() void
        +set_param(key, value) void
        +get_state() State
    }
    class DeviceSource {
        -device_id : int
        -wasapi_handle : void*
        +enumerate() List~Device~
    }
    class ToneSource {
        -freq : float
        -amp : float
        -waveform : Waveform
    }
    class WavSource {
        -file_path : string
        -mmap_buffer : char*
    }
    ISource <|.. DeviceSource
    ISource <|.. ToneSource
    ISource <|.. WavSource

9.5 stateDiagram-v2 状态图

stateDiagram-v2
    [*] --> Idle
    Idle --> Preparing : prepare()
    Preparing --> Running : start()
    Running --> Pausing : pause()
    Pausing --> Paused
    Paused --> Running : resume()
    Running --> Stopping : stop()
    Stopping --> Stopped
    Stopped --> [*]
    Idle --> Error : on_error
    Running --> Error : on_error
    Error --> Idle : reset()

9.6 gantt 甘特图

gantt
    title Source 模块 P0-P2 路线图
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    section P0 · 基础三源
    Device 实现       :done,    p0a, 2026-03-01, 14d
    Tone 实现         :done,    p0b, 2026-03-15, 7d
    WAV 实现          :done,    p0c, 2026-03-22, 10d

    section P1 · 性能优化
    WASAPI 抖动修复   :active,  p1a, 2026-04-01, 14d
    Tone FM 调制      :         p1b, 2026-04-15, 10d

    section P2 · 高级特性
    多通道路由        :         p2a, 2026-05-01, 21d
    ASIO 支持(待评估) :         p2b, 2026-06-01, 30d

10. 数学公式

行内公式:声压级 \(L_p = 20 \log_{10}(p / p_0)\) dB,其中 \(p_0 = 20\,\mu\text{Pa}\)。

块级公式(信噪比定义):

\[ \text{SNR} = 20 \cdot \log_{10}\left(\frac{A_{\text{signal}}}{A_{\text{noise}}}\right) \quad \text{[dB]} \]

频域采样定理:

\[ f_s \geq 2 \cdot f_{\max} \]

公式渲染依赖 KaTeX/MathJax

当前 mkdocs.yml 启用了 pymdownx.arithmatex: generic: true,但未在 extra_javascript 中加载 KaTeX/MathJax。 上面公式会显示为占位字符串 \( ... \) 或 \[ ... \],而不是渲染后的公式。 如果格式 demo 通过,后续可在 mkdocs.yml 增加: 

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

11. 图片与图注

Xisound Logo 占位

图 11-1 · Xisound 三色 Logo(本地资源)

外链占位

图 11-2 · 外链占位图(用 placehold.co 临时生成)

12. 链接

13. 缩写 abbr

DSP 指 digital signal processing,WASAPI 指 Windows Audio Session API,IDE 指 integrated development environment。

(把鼠标悬停在上面的 DSP / WASAPI / IDE 上会显示完整解释)

14. emoji

常用 emoji:✅ 通过 / ❌ 失败 / ⚠️ 警告 / 🎯 目标 / 📊 数据 / 🔥 热点 / 💡 灵感 / 🚀 发布 / 🐛 bug / 📝 笔记 / 🎨 设计 / 🧪 实验 / 🏷️ 标签 / 🔧 工具 / 📦 模块。

Material 短码::material-music: :material-waveform: :material-microphone:(短码渲染依赖 pymdownx.emoji)。

15. 特殊组件(xy-quote / xy-stack / xy-workflow)

15.1 引言卡 xy-quote

"
让上游算法看不见数据来自哪里 —— Source 模块的存在意义
— XISTUDIO ARCHITECTURE COUNCIL

15.2 五层堆叠 xy-stack

L5
XiMind 云端智能
Cloud · 远程编排 · 模型推理
CLOUD
L4
XiStudio 工坊 IDE
Tooling · 可视化算法编辑器
TOOL
L3
XiAlgo 算法引擎(本文重点)
Algorithm · DSP Core · Source/Sink/Mixer/EQ
CORE
L1
XiAmp / XiBox 硬件
Hardware · 功放 / 音频盒
HW
L0
XiDSP 芯片
Silicon · 车规级音频 DSP
SoC

15.3 数字步骤工作流 xy-workflow

  1. 用户在 XiStudio 拖入 Source 节点,前端发 WebSocket source.create 请求
  2. 后端 C# 服务接到请求,调 SourceFactory.Create(SourceType.Tone) 创建实例
  3. DSP 引擎在下次 tick 时拉取首帧采样,Source 进入 Running 状态
  4. 前端通过 source.subscribe(id) 订阅状态变化,UI 实时更新
  5. 用户点击 Stop 按钮,发 source.stop,后端调 src.Stop(),Source 回到 Idle

16. Material grid cards(卡片网格)

  • :material-music: Source 模块

    统一抽象 device / tone / wav 三类输入,上游算法看不见数据来源。

    → 阅读架构文档

  • :material-waveform: Mixer 模块

    多通道混音 + 增益 + 路由,支持 N×M 矩阵。

    → 阅读架构文档

  • :material-tune: EQ 模块

    参数化 EQ + 图形 EQ,8 段 / 31 段切换。

    → 阅读架构文档

  • :material-bug: 诊断工具

    实时频谱 + 时域波形 + 相位图三视图。

    → 阅读用户手册

17. 验收检查清单

  • H1-H6 全部展示
  • 段落 / mark / sup / sub / strong / em 全部展示
  • 无序 / 有序 / 任务清单 / 定义列表
  • 引用(单层 + 多层嵌套)
  • 表格(三对齐 + emoji 头 + 长内容)
  • 12 类 admonition + 折叠 details(open/closed)
  • 8 种代码语言 + 行号 + 高亮 + 注解
  • Tabs(代码 4 + 内容 4)
  • Mermaid 6 类(flowchart 简单 + 含 subgraph + sequence + class + state + gantt)
  • 数学公式(行内 + 块级)
  • 图片(本地 + 外链)+ 图注
  • 链接(内部 + 锚点 + 外部 + 邮件 + 脚注)
  • 缩写 + 定义列表 + emoji
  • 特殊组件:xy-quote / xy-stack / xy-workflow / grid cards

format-demo · 套 0 · current xiyin · v0.1 · 2026-05-10

  1. JUCE 是英国 Raw Material Software 维护的 C++ 音频框架,Apache 2.0 协议。 ↩

  2. SuperCollider 是开源音频合成与算法作曲平台,源于 1996 年。 ↩