tldr 仓库中的 `pw-midiplay`：PipeWire MIDI 播放别名命令的用法与别名页机制解析-开发者社区

文档
教程
知识库

【免费下载链接】tldr

Collaborative cheatsheets for console commands 📚.

项目地址：https://gitcode.com/GitHub_Trending/tl/tldr

pw-midiplay是 tldr 文档仓库中针对 PipeWire 播放工具的一个别名页（alias page），它指向pw-cat --playback --midi，专门用于播放 MIDI 文件。本文以该别名页为核心，介绍它的查询方式、背后原命令的完整 MIDI 用法，以及 tldr 项目如何用模板和脚本维护这类别名页。

别名页的核心内容：pw-midiplay 指向什么

在 tldr 仓库中，pages.ar/linux/pw-midiplay.md 是一份阿拉伯语别名页，正文仅保留两个核心信息：

# pw-midiplay > هذا الأمر هو اسم مستعار لـ `pw-cat --playback --midi`. - إعرض التوثيقات للأمر الأصلي: `tldr pw-cat`

翻译过来即：

pw-midiplay是pw-cat --playback --midi的别名——也就是说，执行pw-midiplay等价于通过 PipeWire 以回放（playback）模式处理 MIDI 数据；
查看原命令文档：tldr pw-cat。

与其英文原版 pages/linux/pw-midiplay.md（内容为> This command is an alias ofpw-cat --playback --midi.加tldr pw-cat）完全对应，只是按项目阿拉伯语模板做了翻译。这样的页面在整个仓库共有 39 个语言版本，分布在pages.*各语言目录的linux/平台目录下。

在 tldr 客户端中如何查询与使用

安装了任一 tldr 客户端后，查询别名命令的方式与普通命令一致：

tldr pw-midiplay

客户端会渲染出上面的别名页，告诉你该命令真实身份是pw-cat --playback --midi，并提示你查看原命令文档。接着执行：

tldr pw-cat

即可获得 PipeWire 音频播放/录制工具pw-cat的完整速查页。实际要运行 MIDI 播放时，直接输入pw-midiplay或在终端执行pw-cat --playback --midi均可，因为pw-midiplay本质上就是后者的便捷别名。

原命令`pw-cat`的 MIDI 实战用法

既然pw-midiplay只是入口，真正的能力集中在原命令 pages/linux/pw-cat.md 中。pw-cat用于通过 PipeWire 播放和录制音频文件，它同时列出wpctl、pw-cli作为相邻参考命令。与 MIDI 直接相关的用法如下：

播放一个 MIDI 文件（这正是pw-midiplay展开后的形式）：

pw-cat --playback --midi {{path/to/file.mid}}

录制 MIDI 文件：

pw-cat --record --midi {{path/to/file.mid}}

--playback（回放）与--record（录制）是pw-cat的两大核心模式，--midi则把 I/O 方向切到 MIDI 类型，因此别名页把pw-midiplay定义为pw-cat --playback --midi——它只负责 MIDI 回放，录制方向请直接用pw-cat --record --midi。

pw-cat还支持其他媒体类型与参数，方便与 MIDI 用法对照：

模式	命令示例	用途
回放 WAV	`pw-cat --playback {{path/to/file.wav}}`	默认目标设备播放 WAV
回放 DSD	`pw-cat --playback --dsd {{path/to/file.dsf}}`	播放 DSD 文件
直通压缩音频	`pw-cat --playback --encoded {{path/to/file.ac3}}`	需 FFmpeg 集成的 passthrough 播放
指定重采样质量	`pw-cat --playback --quality {{0..15}} {{path/to/file.wav}}`	质量档 0–15，默认 4
录制音量	`pw-cat --record --volume {{1.25}} {{path/to/file.wav}}`	以 125% 音量录制
录制采样率	`pw-cat --record --rate {{6000}} {{path/to/file.wav}}`	自定义采样率录制

对比可见：--midi、--dsd、--encoded是同层级的媒体格式开关，而--quality、--volume、--rate属于跨格式的通用参数。

tldr 别名页的仓库级规范：模板与自动生成

pw-midiplay.md并非手工随意书写，而是严格遵循项目的别名页模板。在 contributing-guides/translation-templates/alias-pages.md 中，阿拉伯语模板（### ar）定义如下：

# example > هذا الأمر هو اسم مستعار لـ `example`. - إعرض التوثيقات للأمر الأصلي: `tldr example`

该模板同时规定了 39 种语言的统一结构，所有别名页都要求三要素：#标题、>描述行（声明原命令）、以及一条tldr <原命令>示例行。页面上文件名为pw-midiplay.md、标题为pw-midiplay、原命令为pw-cat --playback --midi、查询命令为pw-cat，正是模板中四个example占位符被逐一替换的结果。

这个替换过程由仓库脚本 scripts/set-alias-page.py 自动化完成。从源码看，它的工作流程是：

generate_alias_page_content()按顺序把模板中的example替换为标题、原命令和文档命令（见#L120-L142）；
set_alias_page()按语言模板将别名页写入对应语言目录，并对比现有内容决定"新增/更新"（见#L145-L210）；
sync_alias_page_to_locale()/get_english_alias_pages()负责把英文别名页同步到所有语言目录（见#L285-L341）。

维护者可用如下命令同步所有语言的别名页，或限定单语种、仅演练（dry-run）：

python3 scripts/set-alias-page.py --sync # 同步全部语言 python3 scripts/set-alias-page.py --sync -l ar # 仅同步阿拉伯语 python3 scripts/set-alias-page.py --sync --dry-run # 预览变更

此外，contributing-guides/style-guide.md 的Aliases章节（见#L96-L104）说明：当命令可用别名调用时（例如vi之于vim），就应创建别名页把用户引向原命令——pw-midiplay正是这一规范在 PipeWire 工具链上的实例。

延伸：PipeWire 工具链中的相邻命令

pw-midiplay所在的 Linux 平台目录还收录了 PipeWire 生态的另外两个管理工具，适合一起速查：

pages/linux/wpctl.md：管理 WirePlumber（PipeWire 的会话与策略管理器），如wpctl status列出所有对象、wpctl set-volume {{sink_id}} {{n}}%设置音量、wpctl set-mute @DEFAULT_SINK@ {{1|0|toggle}}静音/取消静音；
pages/linux/pw-cli.md：管理 PipeWire 实例的模块、对象、节点、设备与链接，如pw-cli ls {{Node|Link|Port|Client|...}}列出指定类型对象、pw-cli info {{4}}按 ID 查看对象信息。

三者角色互补：pw-cat（及其别名pw-midiplay）负责实际播放/录制，wpctl负责会话级控制，pw-cli负责底层对象管理，共同覆盖 PipeWire 的日常操作。

小结

pw-midiplay的 tldr 别名页虽短，却完整体现了项目的两类设计：对外，它以最简信息告诉用户"该命令就是pw-cat --playback --midi"，并通过tldr pw-cat引导至包含全部播放/录制参数的完整速查页；对内，它是模板（alias-pages.md）与自动化脚本（set-alias-page.py）协同产出的标准产物。需要播放 MIDI 文件时，直接运行pw-midiplay {{path/to/file.mid}}即可，需要更复杂操作则回到pw-cat的完整参数体系。