DRAFT

✨ Style C · Notion / Apple(柔米黄整页 + 圆角大卡)

格式 Demo · 套 C · Notion/Apple 风

本 demo 的定位

风格:借鉴 Notion / Apple Developer / Tailwind Docs 的柔和阅读体验
核心特征:大留白 / 圆角大卡 / 浅彩底 admonition / 表格圆角 + 浅阴影 / 玫瑰金小圆点 + 渐变锚条
正文内容:与套 0/A/B 完全一致(便于对比)——XiStudio Source 模块运行 demo
隔离方式:整篇正文用 <div class="xy-style-c"> 包裹,顶部内联 <style> 块定义,不影响其他文档

1. 标题层级

1.1 H3 子节标题

H3 在 Notion 风下:左侧玫瑰金小圆点 + 三色光晕,字体偏大,留白舒展。

1.1.1 H4 细分

H4 用更大的字号 + 灰色,无大写无字距。

1.1.1.1 H5 细分(罕用)

1.1.1.1.1 H6 细分(几乎不用)

2. 段落与文本强调

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

行内代码示例:device_id=2 source_module.h:42 --no-pager(套 C 下行内代码是浅金底 + 玫瑰金字 + 大圆角)。

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

数学公式上下标:H₂O 与 E=mc²,标记重要术语,删除 ~~过时方案~~。

3. 列表

3.1 无序列表(嵌套)

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

3.2 有序列表

用户在 XiStudio 拖入 Source 节点
前端发 WebSocket source.create 请求
后端创建 SourceModule 实例
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 行)

#include <xistudio/source.h>

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

这是 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

cd AlgoDepartment/06_docs/site-build
python -m mkdocs serve --dev-addr 127.0.0.1:8765

7.5 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);

8. Tabs 切换

8.1 代码 Tabs

PythonTypeScriptCC#

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(平台差异)

WindowsmacOSLinuxiOS

使用 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]} \]

公式渲染依赖 KaTeX/MathJax(全 4 套 demo 均同此问题)

需在 mkdocs.yml 增加 KaTeX/MathJax CDN 才能正确渲染。

11. 图片与图注

图 11-1 · Xisound 三色 Logo

外链占位

图 11-2 · 套 C 主题占位图

12. 链接

内部相对链接:品牌色彩系统 v1.1
内部锚点:跳转到 § 9.1 Flowchart
外部链接:Notion / Apple Developer(本套风格的灵感来源)
邮件链接:hello@xisound.com
自动 URL:https://docs.joysnd.com/
脚注引用:Notion¹ 和 Apple Developer Docs² 是本套设计的主要参考。

13. 缩写 abbr

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

14. emoji

常用 emoji:✅ 通过 / ❌ 失败 / ⚠️ 警告 / 🎯 目标 / 📊 数据 / 🔥 热点 / 💡 灵感 / 🚀 发布 / 🐛 bug / 📝 笔记。

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

15.1 引言卡 xy-quote

"

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

— XISTUDIO ARCHITECTURE COUNCIL

15.2 五层堆叠 xy-stack

L5

XiMind 云端智能

  <div class="xy-stack-desc">Cloud · 远程编排 · 模型推理

</div>
<div class="xy-stack-tag">CLOUD</div>

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

用户在 XiStudio 拖入 Source 节点,前端发 WebSocket source.create 请求
后端 C# 服务接到请求,调 SourceFactory.Create(SourceType.Tone) 创建实例
DSP 引擎在下次 tick 时拉取首帧采样,Source 进入 Running 状态
前端通过 source.subscribe(id) 订阅状态变化,UI 实时更新
用户点击 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 全部展示(Notion 风:H1 大字 + 玫瑰金渐变锚条,H2 大字号阶梯,H3 玫瑰金小圆点带光晕)
所有正文元素与套 0/A/B 对齐(便于对比)
内联 <style> 完全自包含,不影响其他文档
暗色模式适配
Hero 仍走品牌主题(共用 4 套统一形象)

format-demo · 套 C · notion/apple · v0.1 · 2026-05-10

Notion · 圆角大卡 + 大留白 + 浅彩底 admonition,阅读体验流畅。 ↩
Apple Developer Documentation · SF Pro 大字 + 玫瑰金锚条 + 浅卡片化。 ↩