Add: Documentation for using the beep command (#682)

Refer to the beep --help and the beep documentation in the man pages for writing.

Author: ischenyu

command/beep.md

@@ -0,0 +1,188 @@
+beep
+===
+
+用于控制 PC 扬声器发出蜂鸣声的命令行工具。
+
+## 介绍
+
+`beep` 是一个用于精确控制 PC 扬声器发出蜂鸣声的命令行工具。它可以生成不同频率、时长、重复次数和延迟的蜂鸣音，支持将多个音调组合成序列，或根据标准输入（stdin）的换行符/字符触发蜂鸣。该工具常用于 shell 或 Perl 脚本中，在特定事件发生时向用户发出音频提示。
+
+**注意**：`beep` 需要 PC 扬声器硬件支持，通常需要加载 `pcspkr` 内核模块，并且对输出设备具有写入权限。
+
+## 安装
+Debian/Ubuntu:
+```bash
+sudo apt install beep
+```
+
+RedHel/Centos/Fedora:
+```bash
+sudo yum install beep
+```
+
+## 语法
+```bash
+beep [全局选项] [音调选项] [-n|--new 音调选项...]...
+beep [-h|--help]
+beep [-v|-V|--version]
+```
+
+## 选项说明
+
+### 信息选项
+| 选项            | 描述                               |
+|----------------|-----------------------------------|
+| `-h, --help`   | 显示帮助信息并退出。                 |
+| `-v, -V, --version` | 显示版本信息并退出。           |
+
+### 全局选项
+| 选项                       | 描述                                                         |
+|---------------------------|-------------------------------------------------------------|
+| `-e, --device=DEVICE`     | 显式指定用于输出蜂鸣的设备。若不指定，`beep` 会依次尝试内部设备列表直到成功。 |
+| `--debug, --verbose`      | 启用详细输出，显示调试信息。                                 |
+
+### 音调选项
+每个音调可以由以下选项组合定义。若未指定，使用默认值。
+
+| 选项                | 描述                                                                 |
+|--------------------|---------------------------------------------------------------------|
+| `-f FREQ`          | 设置蜂鸣频率（单位：Hz）。必须满足 0 < FREQ < 20000。可接受浮点数，但内核 API 会取整为整数。默认值：440 Hz。 |
+| `-l LEN`           | 设置蜂鸣时长（单位：ms）。默认值：200 ms。                          |
+| `-r REPEATS`       | 设置当前音调的重复次数（包括延迟）。默认值：1（仅一次，无重复）。    |
+| `-d DELAY`         | 设置重复之间的延迟（单位：ms），**不**在最后一次重复后添加延迟。默认值：100 ms。 |
+| `-D DELAY`         | 设置重复之间的延迟（单位：ms），**并**在最后一次重复后也添加该延迟。默认无延迟。 |
+| `-n, --new`        | 开始定义一个新的音调。每个 `-n` 之后可以跟一组新的音调选项，新音调继承所有默认值，直到被显式选项覆盖。 |
+| `-s`               | 将 `beep` 置于输入处理模式：从标准输入读取数据，每遇到一个**换行符**就发出当前定义的音调一次，同时将输入数据原样复制到标准输出。 |
+| `-c`               | 与 `-s` 类似，但每遇到一个**字符**就触发一次蜂鸣。                  |
+
+**注意**：
+- `-d` 和 `-D` 的区别：`-r 3 -d 100` 产生：蜂鸣、延迟、蜂鸣、延迟、蜂鸣（结束）；`-r 3 -D 100` 产生：蜂鸣、延迟、蜂鸣、延迟、蜂鸣、延迟（结束）。
+- 在一个由 `-n` 连接的多个音调序列中，**只能有一个音调**带有 `-s` 或 `-c`。`beep` 会先播放该音调之前的所有音调，然后进入输入处理模式，根据输入重复该音调，直到输入结束（EOF），最后再播放剩余的音调（如果有）。
+- 如果某个选项在命令行中重复出现，后面的选项会覆盖前面的。
+
+
+## 环境变量
+| 变量名            | 描述                                                                 |
+|------------------|---------------------------------------------------------------------|
+| `BEEP_LOG_LEVEL` | 设置日志级别（取值范围 -999 到 999）。若未在命令行使用 `--debug`，则以此值为默认日志级别。 |
+
+
+## 文件
+`beep` 默认依次尝试打开以下设备，直到成功为止：
+- `/dev/input/by-path/platform-pcspkr-event-spkr`（使用 evdev API）
+- `/dev/tty0`（使用 console API）
+- `/dev/vc/0`（使用 console API）
+
+
+## 退出状态
+| 状态码 | 含义                     |
+|--------|--------------------------|
+| 0      | 成功执行                 |
+| 非0    | 发生错误（如设备无法打开、无效参数等） |
+
+
+## 注意事项
+
+### 设备和权限
+- **非 root 用户**：默认情况下，`/dev/tty0` 和 `/dev/vc/0` 需要 root 权限或拥有当前 TTY。推荐使用 evdev 设备 `/dev/input/by-path/platform-pcspkr-event-spkr`，可以通过 udev 规则为该设备设置适当的权限，使普通用户也能使用 `beep`。
+- `beep` **不支持**以 setuid root 或通过 `sudo` 运行。请通过文件权限或 udev 规则授权。
+- 如果命令不能正常执行，请检查 `pcspkr` 模块是否加载。
+
+### API 说明
+- **evdev**：使用输入事件设备驱动，通过 `write()` 操作。打开设备耗时约 20ms，因此若要演奏旋律，建议在单个 `beep` 命令中使用多个音调（通过 `-n`），而不是多次调用 `beep`。
+- **console**：使用古老的 `KIOCSOUND ioctl` 接口，仅当用户登录到虚拟控制台（如 `/dev/tty4`）且拥有该终端时才可无 root 使用。对通过 SSH 或图形界面登录的用户不适用。
+
+### 并发调用
+`beep` 不支持并发运行。PC 扬声器硬件只有一个发声器，多个 `beep` 进程会相互干扰。例如，一个长蜂鸣进程正在运行时，另一个短蜂鸣进程会中断前者，且前者之后会静默关闭扬声器，导致预期外的静音。
+
+### 音量控制
+- 独立 PC 通常使用压电蜂鸣器，其音量与频率相关，接近共振频率（约 2000 Hz）时最响。可尝试 2050 Hz 左右获得最大音量。
+- 笔记本电脑可能将 PC 扬声器输出路由到内置扬声器，此时可通过声卡混音器调节“Beeper”或“PC Speaker”通道的音量。
+
+### 频率参考表
+以下是音乐音符与频率的对应关系。
+
+| 音符 | 八度 3 | 八度 4 | 八度 5 | 八度 6 |
+|------|--------|--------|--------|--------|
+| C    | 131    | 262    | 523    | 1047   |
+| C#   | 139    | 277    | 554    | 1109   |
+| D    | 147    | 294    | 587    | 1175   |
+| D#   | 156    | 311    | 622    | 1245   |
+| E    | 165    | 330    | 659    | 1319   |
+| F    | 175    | 349    | 698    | 1397   |
+| F#   | 185    | 370    | 740    | 1480   |
+| G    | 196    | 392    | 784    | 1568   |
+| G#   | 208    | 415    | 831    | 1661   |
+| A    | 220    | 440    | 880    | 1760   |
+| A#   | 233    | 466    | 932    | 1865   |
+| B    | 247    | 494    | 988    | 1976   |
+| C    | 262    | 523    | 1047   | 2093   |
+
+
+## 实例
+
+### 1. 简单蜂鸣
+```bash
+beep
+```
+发出默认蜂鸣（440 Hz，200 ms）。
+
+### 2. 指定频率和时长
+```bash
+beep -f 800 -l 500
+```
+发出 800 Hz 的蜂鸣，持续 500 毫秒。
+
+### 3. 重复蜂鸣
+```bash
+beep -f 600 -l 100 -r 3 -d 50
+```
+重复 3 次，每次 100 毫秒，间隔 50 毫秒，最后一次后无延迟。
+
+```bash
+beep -f 600 -l 100 -r 3 -D 50
+```
+重复 3 次，每次 100 毫秒，间隔 50 毫秒，且最后一次后也有 50 毫秒延迟。
+
+### 4. 两个不同音调
+```bash
+beep -f 400 -l 200 -n -f 800 -l 200
+```
+先发 400 Hz 音（200 ms），紧接着发 800 Hz 音（200 ms），音调间无额外延迟。
+
+### 5. 音调间加入延迟（通过前一个音调的 -D）
+```bash
+beep -f 400 -l 200 -D 100 -n -f 800 -l 200
+```
+先发 400 Hz 音，然后延迟 100 ms（因为 -D 使该音调最后附加了延迟），再发 800 Hz 音。
+
+### 6. 每次换行蜂鸣
+```bash
+tail -f /var/log/syslog | beep -s
+```
+每当日志有新行写入，就发出当前定义的音调（默认 440 Hz）。
+
+### 7. 每输入一个字符蜂鸣（打字机效果）
+```bash
+cat /dev/stdin | beep -c
+```
+在终端输入字符，每按一个键（包括回车）就会蜂鸣一次，输入内容同时显示。
+
+### 8. 使用自定义设备
+```bash
+beep -e /dev/input/by-path/platform-pcspkr-event-spkr -f 1000
+```
+通过指定 evdev 设备发出 1000 Hz 蜂鸣。
+
+### 9. 复杂序列：先奏一段音调，然后根据输入重复某个音调，最后收尾
+```bash
+beep -f 523 -l 200 -n -f 659 -l 200 -n -f 784 -l 200 -n -s -f 440 -l 100 -r 3 -n -f 523 -l 400
+```
+先播放 C5（523 Hz）、E5（659 Hz）、G5（784 Hz）各 200 ms（音调间无延迟）；然后进入输入处理模式，每遇到一个换行符就播放 A4（440 Hz）三次（每次 100 ms，间隔默认 100 ms）；输入结束后（Ctrl+D），最后播放一个长的 C5（523 Hz，400 ms）。
+
+
+## 相关文档
+更详细的信息可以参考`man`：
+```bash
+man beep
+```