@casatwy/deyo 0.1.6 → 0.1.9

package/README.md

@@ -1,8 +1,10 @@
 # deyo
 
-`deyo` 是 [https://deyo.miaobi.fun](https://deyo.miaobi.fun) 的命令行工具。你可以直接在终端里提交音视频链接进行转写，并把结果输出到终端或保存到本地文件。
+`deyo` 是 [https://deyo.miaobi.fun](https://deyo.miaobi.fun) 的命令行工具。你可以直接在终端里提交音视频链接或本地音视频文件进行转写，并把结果输出到终端或保存到本地文件。
 
-当前支持的来源包括小宇宙单集、B 站单视频、抖音单视频、小红书单视频笔记、YouTube 单视频和 Apple Podcasts 单集。
+当前支持 8 类链接来源 + 本地音视频上传。链接来源包括小宇宙单集、喜马拉雅单集（含 `xima.tv` 短链）、B 站单视频、抖音单视频、小红书单视频笔记、YouTube 单视频、Apple Podcasts 单集和 Twitter/X 单条推文。其中喜马拉雅合集链接会返回 422 并提示选择单集，不会扣分钟或创建转写任务；Twitter/X 只有视频推文可转写，文本 / 图片推文会返回 422。B 站支持普通 BV 链接、`b23.tv` 短链、带 `bvid` 的 `player.bilibili.com/player.html` 嵌入播放器链接，以及可由 Whisper 解出 BV 页面的 `bilibili://video/...` App 分享视频链接；CLI 会识别并透传 App 链接，不在本地解码或推导 BV。
+
+本地文件转写只支持单个音频或视频文件。你可以直接传文件路径，也可以显式使用 `--file`；如果文件扩展名或系统识别不可靠，可以用 `--mime-type` 指定媒体类型。当前不支持目录、glob、stdin、批量队列或断点续传。
 
 ## 安装
 
@@ -60,12 +62,19 @@ deyo auth logout
 deyo 'https://www.youtube.com/watch?v=xxxx'
 ```
 
-这条命令会：
+也可以直接给一个本地音视频文件：
+
+```bash
+deyo ./audio.mp3
+```
+
+这类命令会：
 
 1. 使用你本地已保存的 API Key
-2. 提交一个转写任务
-3. 在终端里持续显示任务进度
-4. 完成后直接把结果输出到终端
+2. 提交一个链接转写或文件上传任务
+3. 对本地文件显示上传百分比，并在服务端完成媒体检查
+4. 在终端里持续显示任务创建、状态切换和转写进度
+5. 完成后直接把结果输出到终端
 
 如果你希望把结果保存到文件：
 
@@ -73,6 +82,12 @@ deyo 'https://www.youtube.com/watch?v=xxxx'
 deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 ```
 
+显式使用文件参数并指定 MIME type：
+
+```bash
+deyo --file ./audio.mp3 --mime-type audio/mpeg -O ./audio.txt
+```
+
 ## 常见用法
 
 处理小宇宙单集并保存为文本：
@@ -81,12 +96,61 @@ deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 deyo -O ./episode.txt 'https://www.xiaoyuzhoufm.com/episode/xxxx'
 ```
 
+处理喜马拉雅单集并保存为文本：
+
+```bash
+deyo -O ./ximalaya.txt 'https://www.ximalaya.com/sound/963656969'
+```
+
+也可以传入会跳转到单集页的 `xima.tv` 短链；合集链接会直接提示需要选择具体单集链接后再提交。
+
+处理 Twitter/X 视频推文并保存为文本：
+
+```bash
+deyo --source twitter -O ./tweet.txt 'https://x.com/historyinmemes/status/1790637656616943991'
+```
+
+如果传入 Twitter/X 文本或图片推文，CLI 会提示当前不支持转写；这类内容不会进入支付或分钟扣减链路。
+
+处理本地音频文件并保存为文本：
+
+```bash
+deyo ./audio.mp3 -O ./audio.txt
+```
+
+等价地，也可以显式写成：
+
+```bash
+deyo --file ./audio.mp3 -O ./audio.txt
+deyo -O ./audio.txt -- ./audio.mp3
+```
+
+如果需要覆盖自动识别出的媒体类型：
+
+```bash
+deyo --file ./recording.m4a --mime-type audio/mp4 -O ./recording.txt
+```
+
+本地文件上传同样使用 API key 鉴权。文件通过媒体检查并创建完整转写任务后，会按账号分钟余额扣减；如果分钟不足，需要先充值分钟包。
+
 保存为普通文本：
 
 ```bash
 deyo -O ./transcript.txt 'https://www.bilibili.com/video/BVxxxx'
 ```
 
+处理 B 站嵌入播放器链接时，需要链接里带有 `bvid`。CLI 会把它保存为标准 BV 页面 URL；`p` 优先、`page` 兜底选择分 P，`cid` 会被忽略：
+
+```bash
+deyo -O ./bilibili.txt 'https://player.bilibili.com/player.html?bvid=BVxxxx&page=2&cid=123456'
+```
+
+处理 B 站 App 分享的视频链接时，可以直接传 `bilibili://video/...`。CLI 只负责识别为 B 站来源并提交原始 App 链接；`h5awaken.open_app_url`、`h5awaken` base64 内 `open_app_url` 和路径 BV 号的解析由 Whisper 服务端完成。如果只有纯数字 aid 且服务端无法解出 BV 页面，请改用普通 BV 页面 URL：
+
+```bash
+deyo -O ./bilibili-app.txt 'bilibili://video/BVxxxx?page=2'
+```
+
 导出为 `srt` 字幕文件：
 
 ```bash
@@ -123,6 +187,14 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 
 把结果写入文件。如果不传这个参数，结果会直接打印到终端。
 
+`--file <path>`
+
+显式指定一个本地音频或视频文件。也可以直接把文件路径作为位置参数传给 `deyo`，例如 `deyo ./audio.mp3`。
+
+`--mime-type <value>`
+
+可选。覆盖 CLI 自动识别出的文件媒体类型，例如 `audio/mpeg`、`audio/mp4`、`video/mp4`。一般不需要传，只有扩展名不明确或自动识别不符合预期时再使用。
+
 `--format <value>`
 
 指定结果格式，支持：
@@ -150,7 +222,9 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 - 当 stderr 是 TTY 时，会保留当前的单行原地刷新进度体验
 - 当 stderr 不是 TTY 时，会退化成逐行文本进度，避免控制字符污染日志或代理输出
 
-如果你希望 AI 或脚本稳定读取进度事件，建议使用 `--progress-format jsonl`。此时 CLI 会继续把最终结果输出到 stdout 或文件，只把进度事件按 JSON Lines 写到 stderr。
+如果你希望 AI 或脚本稳定读取进度事件，建议使用 `--progress-format jsonl`。此时 CLI 会继续把最终结果输出到 stdout 或文件，只把进度事件按 JSON Lines 写到 stderr。AI 代跑上传或长转写任务时，应读取 JSONL 后用自然语言转述上传百分比、媒体检查、任务创建、状态变化和关键转写百分比，不要把原始 JSONL 直接贴给用户。
+
+本地文件上传会额外输出这些上传事件：`upload.hashing`、`upload.started`、`upload.progress`、`upload.completed`、`upload.checking`、`upload.ready`、`upload.aborted`、`upload.failed`。事件不会包含签名 URL、文件 hash 或分片 ETag。
 
 `--api-key <key>`
 
@@ -158,6 +232,13 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 如果你已经执行过 `deyo auth login`，平时通常不需要再传。  
 当它和本地已保存配置同时存在时，会优先使用这次命令里传入的 `--api-key`。
 
+## 能力边界
+
+- 支持输入：8 类单条链接来源，或一个本地音频/视频文件。
+- 不支持输入：目录、glob、stdin、多个文件批量队列、断点续传。
+- API key 是 CLI 鉴权入口；没有 API key 时不能创建任务。
+- 完整转写会按账号分钟余额扣减；喜马拉雅合集、Twitter/X 文本 / 图片推文等不进入转写的分支不会扣分钟或创建转写任务。
+
 `-v, --version`
 
 打印当前 CLI 版本号并退出，适合快速确认本机装的是哪个版本。
@@ -175,7 +256,7 @@ deyo --api-key 'deyo_sk_other' 'https://www.youtube.com/watch?v=xxxx'
 2. 如何向你索取一次 API Key
 3. 如何在你的本地环境执行 `deyo auth login`
 
-完成后，你就可以让 AI 直接帮你调用 `deyo` 提交转写任务。对于需要在对话里持续同步进度的场景，AI 应优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把任务创建、状态切换、关键百分比和最终结果转述给你。
+完成后，你就可以让 AI 直接帮你调用 `deyo` 提交链接转写或本地文件上传任务。对于需要在对话里持续同步进度的场景，AI 必须优先使用 `--progress-format jsonl`，读取 stderr 里的结构化事件，再把上传百分比、媒体检查、任务创建、状态切换、关键转写百分比和最终结果转述给你，不要粘贴原始 JSONL。
 
 ## 更多帮助