Media: components 341-360

docs/components/341-image-cropper.md

@@ -0,0 +1,55 @@
+# 341 ImageCropper 图片裁剪
+
+## 用途
+
+在图片上拖出裁剪框，可锁定宽高比、按 90 度旋转，输出裁剪矩形。
+
+## 最小示例
+
+```go
+crop := mujica.ImageCrop{} // empty: starts fitted to the image
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ImageCropper(c, examplePhoto, &crop, mujica.ImageCropperOptions{Aspect: 1}).Changed() {
+		_ = crop.Rect // in pixels of the photo turned by crop.Rotation
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ImageCropper(c *ui.Context, src image.Image, crop *ImageCrop, opts ImageCropperOptions) ChoiceResult`
+
+`src` 必填，是标准库 `image.Image`（组件要自己转动像素）。`ImageCrop.Rect` 是旋转 `Rotation` 度之后那张图上的像素矩形；`Rotation` 只能是 0、90、180、270。`Rect` 为空时自动设为最大的居中框。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Aspect` | `float64` | 0 | 锁定宽除以高；0 为自由比例。`Rect` 不符合比例时 panic。 |
+| `Height` | `float32` | 0（即 320） | 舞台高度。 |
+| `Disabled` | `bool` | false | 禁用拖动、按键与旋转。 |
+| `Label` | `string` | "Crop area" | 舞台的无障碍名称。 |
+
+## 状态
+
+- 默认：框外区域压暗，框线与三分线为象牙色，四角有菱形手柄。
+- 聚焦：舞台显示 2 DIP 焦点环；下方读数同时作为无障碍描述。
+- 禁用：MyGo 统一调暗，不响应输入。
+
+## 事件
+
+`Changed()` 在框移动、缩放或旋转后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| 方向键 | 移动裁剪框，每次图片宽度的 1% |
+| Shift+方向键 | 右、下放大，左、上缩小；锁定比例时保持比例 |
+| R / Shift+R | 向右 / 向左旋转 90 度 |
+
+## 限制
+
+- MyGo 的 Painter 不能旋转位图（只有单色图标能转，ui/svg.go:98），所以组件在图片或角度变化时复制一份转好的像素；超大图片会在那一帧花时间。
+- 锁定比例时旋转会重新取最大的居中框，原选区不保留。
+- 拖动角点时，按下点距角 14 DIP 以内才算抓住手柄。

docs/components/342-image-annotator.md

@@ -0,0 +1,59 @@
+# 342 ImageAnnotator 图片标注
+
+## 用途
+
+在图片上画矩形、箭头和文字标注，可选择、移动和删除，并导出标注数据。
+
+## 最小示例
+
+```go
+photo := ui.NewBitmap(examplePhoto)
+var notes []mujica.Annotation
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ImageAnnotator(c, photo, &notes, mujica.ImageAnnotatorOptions{}).Changed() {
+		data, _ := mujica.ExportAnnotations(notes)
+		_ = data // save the JSON
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ImageAnnotator(c *ui.Context, src ui.ImageSource, notes *[]Annotation, opts ImageAnnotatorOptions) ChoiceResult`
+
+`func ExportAnnotations(notes []Annotation) ([]byte, error)` 把标注写成 JSON（kind、x0、y0、x1、y1、text）。
+
+`Annotation` 的坐标是图片像素；文字标注以 `From` 为左上角，`Text` 不能为空。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 0（即 320） | 舞台高度。 |
+| `Disabled` | `bool` | false | 禁用绘制、选择和删除。 |
+| `Label` | `string` | "Annotations" | 舞台的无障碍名称。 |
+
+## 状态
+
+- 工具：选择、矩形、箭头、文字，用分段控件切换。
+- 选中：虚线框加菱形标记，不只靠颜色。
+- 标注用暗红墨线加浅色描边，在任何图片上都看得清。
+
+## 事件
+
+`Changed()` 在新增、移动、改字或删除标注后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| [ / ] | 选中上一个 / 下一个标注 |
+| 方向键 | 移动选中的标注，每次图片宽度的 1% |
+| Delete / Backspace | 删除选中的标注 |
+| Escape | 取消选择 |
+
+## 限制
+
+- 文字工具：先在工具栏输入文字，再点击放置；选中文字标注时同一输入框可改字。
+- 标注不能缩放，只能移动；要改大小请删除后重画。
+- 文字的命中区域按每字 8 像素估算。

docs/components/343-image-thumbnail.md

@@ -0,0 +1,54 @@
+# 343 ImageThumbnail 缩略图
+
+## 用途
+
+固定尺寸、按比例裁切的可点击缩略图，带选中、加载中和加载失败状态。
+
+## 最小示例
+
+```go
+photo := ui.NewBitmap(examplePhoto)
+selected := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ImageThumbnail(c, photo, mujica.ImageThumbnailOptions{Alt: "Grand hall", Aspect: 4.0 / 3, Selected: selected}).Changed() {
+		selected = !selected
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ImageThumbnail(c *ui.Context, src ui.ImageSource, opts ImageThumbnailOptions) ChoiceResult`
+
+`src` 为 nil 时显示占位图标。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Width` | `float32` | 0（即 96） | 宽度。 |
+| `Aspect` | `float32` | 0（即 1） | 宽除以高，图片按 Cover 裁切填满。 |
+| `Selected` | `bool` | false | 选中：2 DIP 强调边框加右上角菱形。 |
+| `Loading` | `bool` | false | 显示加载标记，尺寸不变。 |
+| `Err` | `error` | nil | 显示失败图标；错误文字作为提示与描述。 |
+| `Alt` | `string` | 必填 | 替代说明，为空时 panic。 |
+| `Disabled` | `bool` | false | 禁用点击。 |
+
+## 状态
+
+默认、悬停（边框加深）、聚焦、选中、加载、失败、禁用，所有状态尺寸相同。
+
+## 事件
+
+`Changed()` 表示本帧被点击，或聚焦时按了 Enter / Space。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦缩略图 |
+| Enter / Space | 激活 |
+
+## 限制
+
+- 选中状态由调用方保存；组件只报告点击。

docs/components/344-lightbox.md

@@ -0,0 +1,53 @@
+# 344 Lightbox 灯箱
+
+## 用途
+
+全窗口浏览图片：左右切换、显示说明文字，Escape 关闭后焦点回到触发控件。
+
+## 最小示例
+
+```go
+images := []mujica.ViewerImage{{Source: ui.NewBitmap(examplePhoto), Alt: "The grand hall"}}
+open, index := false, 0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Button(c, "View photos", mujica.ButtonOptions{}).Clicked() {
+		open = true
+	}
+	mujica.Lightbox(c, &open, &index, images)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Lightbox(c *ui.Context, open *bool, index *int, images []ViewerImage) ChoiceResult`
+
+与 ImageViewer 共用 `ViewerImage`（`Source`、`Alt`）。`Alt` 同时是说明文字。关闭时 `Element` 为 nil。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `open` | `*bool` | — | 是否显示；Escape、点击关闭或背景时设为 false。 |
+| `index` | `*int` | — | 当前图片；越界 panic。 |
+| `images` | `[]ViewerImage` | — | 至少一张，`Source` 须为 `*ui.Bitmap` 或 `*ui.SVG`。 |
+
+## 状态
+
+- 黑色遮罩铺满窗口，图片按 Contain 居中；首尾时对应切换按钮禁用。
+- 打开时按弹层时长淡入，减少动画时直接出现。
+
+## 事件
+
+`Changed()` 在切换图片后为 true，并朗读“第 n 张，共 m 张”。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ← / → | 上一张 / 下一张 |
+| Home / End | 第一张 / 最后一张 |
+| Escape | 关闭并把焦点还给打开它的控件 |
+
+## 限制
+
+- 不提供缩放与平移；需要时请用 ImageViewer。

docs/components/345-video-player.md

@@ -0,0 +1,59 @@
+# 345 VideoPlayer 视频播放器
+
+## 用途
+
+播放器外壳：画面由调用方提供，组件绘制状态并通过回调报告播放、暂停、跳转、倍速、字幕、全屏和画中画。
+
+## 最小示例
+
+```go
+st := mujica.VideoState{Duration: 4 * time.Minute, Rate: 1}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.VideoPlayer(c, st, mujica.VideoPlayerOptions{
+		OnPlay:  func() { st.Playing = true },  // start your decoder
+		OnPause: func() { st.Playing = false }, // pause it
+		OnSeek:  func(d time.Duration) { st.Position = d },
+		OnRate:  func(r float64) { st.Rate = r },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func VideoPlayer(c *ui.Context, st VideoState, opts VideoPlayerOptions) *ui.Element`
+
+`VideoState`：`Frame`（当前画面，nil 显示“暂无视频”）、`Position`、`Duration`、`Buffered`、`Playing`、`Rate`、`Subtitle`、`SubtitlesOn`、`Fullscreen`、`PiP`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OnPlay / OnPause / OnSeek` | `func` | 必填 | 播放、暂停、跳转。 |
+| `OnRate` | `func(float64)` | nil | 倍速；nil 时不显示倍速选择。 |
+| `OnSubtitles / OnFullscreen / OnPiP` | `func(bool)` | nil | 开关回调；nil 时隐藏对应按钮。 |
+| `Disabled` | `bool` | false | 禁用全部控件。 |
+| `Label` | `string` | "Video" | 无障碍名称。 |
+
+## 状态
+
+- 画面区 16:9，黑底；字幕开启且有字幕时在底部显示。
+- 字幕、画中画、全屏按钮开启时有选中底色和下划线。
+
+## 事件
+
+全部通过回调报告；组件不改动 `st`。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 先聚焦画面，再到进度条和各按钮 |
+| Space / K | 画面聚焦时播放或暂停 |
+| ← / → | 画面聚焦时后退 / 前进 5 秒 |
+| F | 切换全屏 |
+| C | 切换字幕 |
+
+## 限制
+
+- 组件不解码视频，也不实现全屏或画中画窗口，只报告用户的请求。
+- 帧率取决于调用方更新 `Frame` 并调用 `c.Invalidate()` 的频率。

docs/components/346-video-scrubber.md

@@ -0,0 +1,56 @@
+# 346 VideoScrubber 视频时间轴
+
+## 用途
+
+可拖动的时间轴：显示已缓冲区间，悬停显示时间和缩略图插槽。
+
+## 最小示例
+
+```go
+pos := 30 * time.Second
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.VideoScrubber(c, &pos, mujica.VideoScrubberOptions{
+		Duration: 2 * time.Minute,
+		Buffered: []mujica.MediaRange{{Start: 0, End: time.Minute}},
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func VideoScrubber(c *ui.Context, pos *time.Duration, opts VideoScrubberOptions) ChoiceResult`
+
+`*pos` 必须在 0 到 `Duration` 之间，否则 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Duration` | `time.Duration` | 必填 | 时间轴长度，须大于 0。 |
+| `Buffered` | `[]MediaRange` | nil | 已缓冲区间，以浅色填充。 |
+| `Preview` | `func(at time.Duration)` | nil | 悬停时在插槽里构建该时间的缩略图。 |
+| `PreviewWidth / PreviewHeight` | `float32` | 160×90 | 插槽尺寸。 |
+| `Step` | `time.Duration` | 5 秒 | 方向键每次移动的时长。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | "Timeline" | 无障碍名称；以滑块角色报告范围与数值。 |
+
+## 状态
+
+默认、悬停（显示时间气泡）、拖动、聚焦（菱形手柄外圈）、禁用。
+
+## 事件
+
+`Changed()` 在拖动、点击或按键改变 `*pos` 后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ← / ↓ | 后退一个 Step |
+| → / ↑ | 前进一个 Step |
+| Home / End | 开头 / 结尾 |
+
+## 限制
+
+- 位置按毫秒取整。
+- 悬停插槽只在指针位于时间轴上时显示，键盘操作时不显示。

docs/components/347-video-thumbnail-strip.md

@@ -0,0 +1,51 @@
+# 347 VideoThumbnailStrip 缩略帧条
+
+## 用途
+
+横向缩略帧条：标出当前帧，点击或按键跳转。
+
+## 最小示例
+
+```go
+frames := []mujica.StripFrame{{At: 0}, {At: 10 * time.Second}, {At: 20 * time.Second}}
+current := 0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.VideoThumbnailStrip(c, &current, frames, mujica.VideoThumbnailStripOptions{}).Changed() {
+		_ = frames[current].At // seek the player there
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func VideoThumbnailStrip(c *ui.Context, current *int, frames []StripFrame, opts VideoThumbnailStripOptions) ChoiceResult`
+
+`StripFrame` 有 `Image`（可为 nil）和 `At`。`*current` 越界 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `FrameWidth` | `float32` | 0（即 96） | 每格宽度，高度按 16:9。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+- 只构建放得下的那几格，窗口跟随当前帧移动；10 万帧也只建十几个元素。
+- 当前帧：强调边框加菱形；每格左下角显示时间。
+
+## 事件
+
+`Changed()` 在当前帧变化后为 true；调用方据此跳转播放器。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦帧条 |
+| ← / → | 上一帧 / 下一帧 |
+| Home / End | 第一帧 / 最后一帧 |
+
+## 限制
+
+- 不提供横向滚动条，用两侧按钮或键盘移动。

docs/components/348-audio-player.md

@@ -0,0 +1,51 @@
+# 348 AudioPlayer 音频播放器
+
+## 用途
+
+音频播放外壳：播放、暂停、进度与时长，播放本身由调用方驱动。
+
+## 最小示例
+
+```go
+st := mujica.AudioState{Title: "Overture", Duration: 3 * time.Minute}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AudioPlayer(c, st, mujica.AudioPlayerOptions{
+		OnPlay:  func() { st.Playing = true },
+		OnPause: func() { st.Playing = false },
+		OnSeek:  func(d time.Duration) { st.Position = d },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func AudioPlayer(c *ui.Context, st AudioState, opts AudioPlayerOptions) *ui.Element`
+
+`AudioState`：`Title`、`Position`、`Duration`、`Playing`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OnPlay / OnPause / OnSeek` | `func` | 必填 | 缺少任一回调时 panic。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+播放中显示暂停按钮，暂停时显示播放按钮；`Duration` 为 0 时不显示进度条。
+
+## 事件
+
+通过回调报告，组件不改动 `st`。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 播放按钮、进度条 |
+| Space | 组件内任意位置播放或暂停（按钮聚焦时由按钮处理） |
+| ← / → | 进度条聚焦时跳转 5 秒 |
+
+## 限制
+
+- 组件不播放声音。

docs/components/349-audio-waveform.md

@@ -0,0 +1,58 @@
+# 349 AudioWaveform 音频波形
+
+## 用途
+
+绘制调用方提供的采样波形，覆盖播放进度，可拖动选择区间。
+
+## 最小示例
+
+```go
+samples := make([]float32, 48000) // from your decoder, -1 to 1
+pos, sel := time.Duration(0), mujica.MediaRange{}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AudioWaveform(c, samples, mujica.AudioWaveformOptions{
+		Duration: time.Second, Position: pos, Selection: &sel,
+		OnSeek: func(d time.Duration) { pos = d },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func AudioWaveform(c *ui.Context, samples []float32, opts AudioWaveformOptions) ChoiceResult`
+
+`samples` 取值 -1 到 1。数据就绪时 `Duration` 须大于 0，`OnSeek` 必填。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Duration` | `time.Duration` | — | 音频长度。 |
+| `Position` | `time.Duration` | 0 | 已播放部分。 |
+| `OnSeek` | `func(time.Duration)` | — | 点击或方向键跳转。 |
+| `Selection` | `*MediaRange` | nil | 非 nil 时可拖动或 Shift+方向键选择区间。 |
+| `Height` | `float32` | 0（即 96） | 高度。 |
+| `Status / Error` | `DataStatus / string` | DataReady | 加载中、失败（须给 Error）与无数据时显示同尺寸占位。 |
+| `Label` | `string` | "Waveform" | 无障碍名称。 |
+
+## 状态
+
+- 已播放部分用强调色，其余用说明色，并有播放线和菱形标记，不只靠颜色区分。
+- 选区用 Selection 底色加两条边线。
+
+## 事件
+
+`Changed()` 在选区变化后为 true；跳转通过 `OnSeek` 报告。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ← / → | 跳转 ±5 秒 |
+| Shift+← / → | 从播放位置开始或调整选区终点 |
+| Escape | 清除选区 |
+
+## 限制
+
+- 峰值按像素列计算，只在数据或宽度变化时重算，不会每帧计算。
+- 数据以首元素地址和长度识别；原地修改采样请换一个切片。

docs/components/350-audio-spectrum.md

@@ -0,0 +1,49 @@
+# 350 AudioSpectrum 音频频谱
+
+## 用途
+
+把调用方提供的频带数值画成柱状频谱；组件自己不做动画，隐藏时不重绘。
+
+## 最小示例
+
+```go
+bands := []float32{0.2, 0.6, 0.9, 0.4, 0.1} // set by your analyser, then c.Invalidate()
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AudioSpectrum(c, bands, mujica.AudioSpectrumOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func AudioSpectrum(c *ui.Context, bands []float32, opts AudioSpectrumOptions) *ui.Element`
+
+每个频带取 0 到 1，超出范围 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 0（即 120） | 高度。 |
+| `BandLabel` | `func(i int) string` | nil | 读数中频带的名称，如“1 kHz”；nil 时编号。 |
+| `Status / Error` | `DataStatus / string` | DataReady | 加载、失败与无数据占位，尺寸相同。 |
+| `Label` | `string` | "Spectrum" | 无障碍名称。 |
+
+## 状态
+
+聚焦后用方向键选中的频带以正文色显示，带虚线框和读数，不只靠颜色。
+
+## 事件
+
+无事件；方向键读数会通过 `Announce` 朗读。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦频谱 |
+| ← / → | 上一个 / 下一个频带 |
+| Home / End | 第一个 / 最后一个频带 |
+
+## 限制
+
+- 刷新节奏由调用方决定：更新数据后调用 `c.Invalidate()`。

docs/components/351-volume-control.md

@@ -0,0 +1,46 @@
+# 351 VolumeControl 音量控制
+
+## 用途
+
+音量滑块与静音按钮。
+
+## 最小示例
+
+```go
+volume, muted := 0.8, false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.VolumeControl(c, &volume, &muted, mujica.VolumeControlOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func VolumeControl(c *ui.Context, volume *float64, muted *bool, opts VolumeControlOptions) ChoiceResult`
+
+`*volume` 取 0 到 1，超出 panic；步长 5%。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+静音或音量为 0 时显示静音图标；静音按钮开启时有选中底色和下划线。静音时调高音量会自动取消静音。
+
+## 事件
+
+`Changed()` 在音量或静音变化后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ← / → | 音量 ±5% |
+| Home / End | 0% / 100% |
+| M | 组件内切换静音 |
+
+## 限制
+
+- 组件不调节系统音量，只改调用方的值。

docs/components/352-playback-speed-control.md

@@ -0,0 +1,48 @@
+# 352 PlaybackSpeedControl 倍速选择
+
+## 用途
+
+在 0.5× 到 2× 之间选择播放速度。
+
+## 最小示例
+
+```go
+rate := 1.0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.PlaybackSpeedControl(c, &rate, mujica.PlaybackSpeedControlOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func PlaybackSpeedControl(c *ui.Context, rate *float64, opts PlaybackSpeedControlOptions) ChoiceResult`
+
+`*rate` 必须是 `Rates` 中的一项，否则 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Rates` | `[]float64` | 0.5, 0.75, 1, 1.25, 1.5, 2 | 升序的正数。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+基于 Select，状态与键盘同 Select。
+
+## 事件
+
+`Changed()` 在选择新倍速后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Enter / Space | 打开列表 |
+| ↑ / ↓ | 移动 |
+| Enter | 确认 |
+| Escape | 关闭 |
+
+## 限制
+
+- 无。

docs/components/353-media-controls.md

@@ -0,0 +1,53 @@
+# 353 MediaControls 媒体控制
+
+## 用途
+
+上一首、播放/暂停、下一首、循环、随机，一组可用方向键切换焦点的按钮。
+
+## 最小示例
+
+```go
+st := mujica.MediaControlsState{}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.MediaControls(c, st, mujica.MediaControlsOptions{
+		OnPrevious: func() {}, OnNext: func() {},
+		OnPlay: func() { st.Playing = true }, OnPause: func() { st.Playing = false },
+		OnLoop: func(m mujica.LoopMode) { st.Loop = m }, OnShuffle: func(on bool) { st.Shuffle = on },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func MediaControls(c *ui.Context, st MediaControlsState, opts MediaControlsOptions) *ui.Element`
+
+`MediaControlsState`：`Playing`、`Loop`（`LoopOff`、`LoopAll`、`LoopOne`）、`Shuffle`、`NoPrevious`、`NoNext`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OnPrevious / OnPlay / OnPause / OnNext` | `func()` | 必填 | 按钮回调。 |
+| `OnLoop` | `func(LoopMode)` | 必填 | 收到下一个循环模式：不循环 → 列表 → 单曲。 |
+| `OnShuffle` | `func(bool)` | 必填 | 随机开关。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+循环与随机开启时有选中底色和下划线，单曲循环换用带“1”的图标；循环按钮的名称说明当前模式。
+
+## 事件
+
+全部通过回调报告。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 进入按钮组 |
+| ← / → | 在按钮间移动焦点 |
+| Enter / Space | 按下 |
+
+## 限制
+
+- 无。

docs/components/354-playlist.md

@@ -0,0 +1,52 @@
+# 354 Playlist 播放列表
+
+## 用途
+
+播放列表：标出当前项，可拖动排序、移除，只构建可见行。
+
+## 最小示例
+
+```go
+items := []mujica.PlaylistItem{{ID: "a", Title: "Overture"}, {ID: "b", Title: "Masquerade"}}
+current := "a"
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if r := mujica.Playlist(c, &items, mujica.PlaylistOptions{Current: current}); r.Played != "" {
+		current = r.Played
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Playlist(c *ui.Context, items *[]PlaylistItem, opts PlaylistOptions) PlaylistResult`
+
+`PlaylistItem`：`ID`（唯一且非空，否则 panic）、`Title`、`Subtitle`、`Duration`。组件直接修改 `*items` 完成排序和移除。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Current` | `string` | "" | 正在播放项的 ID，显示播放标记和强调文字。 |
+| `Height` | `float32` | 0（即 320） | 列表高度。 |
+| `Disabled` | `bool` | false | 禁用选择、排序和移除。 |
+
+## 状态
+
+基于 List：选中行使用 Selection 底色加勾选标记；空列表显示提示。
+
+## 事件
+
+`PlaylistResult`：`Played` 为 Enter 或双击选择的 ID；`Removed` 为被移除的 ID；`Moved` 表示顺序变化。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ↑ / ↓ | 移动选择 |
+| Enter | 播放选中项 |
+| Alt+↑ / Alt+↓ | 上移 / 下移选中项 |
+| Delete / Backspace | 移除选中项 |
+
+## 限制
+
+- 拖动排序由 MyGo List 的 Reorder 提供，拖动时显示插入线。

docs/components/355-subtitle-editor.md

@@ -0,0 +1,52 @@
+# 355 SubtitleEditor 字幕编辑器
+
+## 用途
+
+逐条编辑字幕的开始、结束时间和文本，校验时间先后与重叠。
+
+## 最小示例
+
+```go
+cues := []mujica.SubtitleCue{{Start: 0, End: 2 * time.Second, Text: "The curtain rises."}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.SubtitleEditor(c, &cues, mujica.SubtitleEditorOptions{})
+	if len(mujica.CheckSubtitles(cues)) > 0 {
+		_ = cues // block saving until the issues are fixed
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func SubtitleEditor(c *ui.Context, cues *[]SubtitleCue, opts SubtitleEditorOptions) ChoiceResult`
+
+`func CheckSubtitles(cues []SubtitleCue) []SubtitleIssue` 返回结束早于开始（`SubtitleEndBeforeStart`）和与上一条重叠（`SubtitleOverlap`）的条目，供调用方阻止保存。时间格式为 `m:ss.mmm` 或 `h:mm:ss.mmm`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Height` | `float32` | 0（即 360） | 列表高度。 |
+| `Disabled` | `bool` | false | 禁用编辑、添加和删除。 |
+
+## 状态
+
+- 无法解析的时间保留在输入框中，并显示格式提示；有效后才写回。
+- 时间问题在该行下方用错误色说明，并报告给辅助技术。
+- 只构建可见行，10 万条也保持流畅。
+
+## 事件
+
+`Changed()` 在任一字段、添加或删除后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 在一行的开始、结束、文本、删除之间移动 |
+| Enter | 提交输入 |
+
+## 限制
+
+- 虚拟化只构建可见行，Tab 不会跳到未显示的行；请先滚动。
+- 组件不排序字幕；顺序由调用方决定。

docs/components/356-screen-recorder-controls.md

@@ -0,0 +1,51 @@
+# 356 ScreenRecorderControls 录屏控制
+
+## 用途
+
+开始、暂停、继续、停止录制并显示计时；录制本身由调用方实现。
+
+## 最小示例
+
+```go
+st := mujica.RecorderState{}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ScreenRecorderControls(c, st, mujica.ScreenRecorderControlsOptions{
+		OnStart:  func() { st.Status = mujica.RecorderRecording },
+		OnPause:  func() { st.Status = mujica.RecorderPaused },
+		OnResume: func() { st.Status = mujica.RecorderRecording },
+		OnStop:   func() { st = mujica.RecorderState{} },
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ScreenRecorderControls(c *ui.Context, st RecorderState, opts ScreenRecorderControlsOptions) *ui.Element`
+
+`RecorderState`：`Status`（`RecorderIdle`、`RecorderRecording`、`RecorderPaused`）、`Elapsed`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OnStart / OnPause / OnResume / OnStop` | `func()` | 必填 | 缺少任一回调时 panic。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+就绪、录制中（红点）、已暂停；状态同时用文字表示，不只靠圆点颜色。录制中的圆点不闪烁。
+
+## 事件
+
+全部通过回调报告。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 在按钮间移动 |
+| Enter / Space | 按下 |
+
+## 限制
+
+- 计时由调用方更新 `Elapsed`。

docs/components/357-camera-preview.md

@@ -0,0 +1,48 @@
+# 357 CameraPreview 摄像头预览
+
+## 用途
+
+显示调用方提供的摄像头帧，无帧时显示“无信号”，可切换镜像。
+
+## 最小示例
+
+```go
+frame := mujica.CameraFrame{Image: examplePhoto, Seq: 1} // a new Seq for each captured frame
+mirror := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.CameraPreview(c, frame, &mirror, mujica.CameraPreviewOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func CameraPreview(c *ui.Context, frame CameraFrame, mirror *bool, opts CameraPreviewOptions) ChoiceResult`
+
+`CameraFrame`：`Image`（标准库 `image.Image`，nil 为无信号）、`Seq`（帧序号，复用同一图像缓冲时用新序号触发重绘）。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | "Camera" | 无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用镜像切换。 |
+
+## 状态
+
+16:9 黑底；镜像按钮开启时有选中底色和下划线。
+
+## 事件
+
+`Changed()` 在镜像切换后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦预览 |
+| M | 切换镜像 |
+
+## 限制
+
+- MyGo 的 Painter 不能水平翻转位图（ui/paint.go:834），所以镜像时组件每个新帧复制一份翻转后的像素；高分辨率帧会占用 CPU。
+- 组件不打开摄像头。

docs/components/358-mic-level-meter.md

@@ -0,0 +1,45 @@
+# 358 MicLevelMeter 麦克风电平
+
+## 用途
+
+分段电平条，带峰值保持与 dB 读数。
+
+## 最小示例
+
+```go
+level := float32(0.4) // the input's peak, 0 to 1 of full scale
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.MicLevelMeter(c, level, mujica.MicLevelMeterOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func MicLevelMeter(c *ui.Context, level float32, opts MicLevelMeterOptions) *ui.Element`
+
+`level` 为满刻度的 0 到 1，超出 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Hold` | `time.Duration` | 1.5 秒 | 峰值保持时长。 |
+| `Label` | `string` | "Microphone level" | 无障碍名称；描述中读出当前与峰值 dB。 |
+
+## 状态
+
+24 段：前 70% 为成功色，接着警告色，最后 10% 为危险色；峰值段为空心标记；右侧显示 dB 数值，不只靠颜色。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| — | 不获取焦点 |
+
+## 限制
+
+- 保持结束时只请求一次重绘，空闲时不持续重绘。

docs/components/359-device-selector.md

@@ -0,0 +1,51 @@
+# 359 DeviceSelector 设备选择
+
+## 用途
+
+选择麦克风、摄像头、扬声器，设备列表由调用方提供。
+
+## 最小示例
+
+```go
+devices := mujica.MediaDevices{
+	Microphones: []mujica.MediaDevice{{ID: "mic-1", Name: "Built-in Microphone"}},
+	Speakers:    []mujica.MediaDevice{{ID: "out-1", Name: "Headphones"}},
+}
+sel := mujica.DeviceSelection{Microphone: "mic-1"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.DeviceSelector(c, &sel, devices, mujica.DeviceSelectorOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DeviceSelector(c *ui.Context, sel *DeviceSelection, devices MediaDevices, opts DeviceSelectorOptions) ChoiceResult`
+
+`MediaDevices` 的某类列表为 nil 时不显示该类；为空切片时显示禁用的“未找到设备”。设备 ID 重复，或已选 ID 不在列表中时 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | false | 禁用全部选择。 |
+
+## 状态
+
+每类一行：图标、名称和 Select。
+
+## 事件
+
+`Changed()` 在任一类选择变化后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 在各选择框间移动 |
+| Enter / Space | 打开列表 |
+| ↑ / ↓ | 移动 |
+| 输入字母 | 跳到匹配的设备 |
+
+## 限制
+
+- 组件不枚举设备，也不监听设备插拔；调用方更新列表即可。

docs/components/360-image-compare.md

@@ -0,0 +1,48 @@
+# 360 ImageCompare 前后对比
+
+## 用途
+
+前后两张图片叠放，用滑块分隔对比。
+
+## 最小示例
+
+```go
+before, after := ui.NewBitmap(examplePhoto), ui.NewBitmap(examplePhoto)
+split := 0.5
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ImageCompare(c, before, after, &split, mujica.ImageCompareOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func ImageCompare(c *ui.Context, before, after ui.ImageSource, split *float64, opts ImageCompareOptions) ChoiceResult`
+
+`*split` 取 0 到 1，表示分隔线位置；超出 panic。两张图都须为 `*ui.Bitmap` 或 `*ui.SVG`，盒子按 `before` 的宽高比。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `BeforeLabel / AfterLabel` | `string` | "Before" / "After" | 两侧标签，也组成无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+分隔线与菱形手柄；两侧标签始终显示，不只靠画面区分。
+
+## 事件
+
+`Changed()` 在分隔位置变化后为 true。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| ← / → | 移动 1% |
+| Home / End | 最左 / 最右 |
+| 拖动 | 任意位置拖动分隔线 |
+
+## 限制
+
+- 两张图都按 Cover 铺满盒子，尺寸不同时会裁切。