video-transcripts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Video Transcripts

视频转录文本

Quick Start

快速开始

Run the helper once per relevant video:

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "https://uploads.linear.app/.../screen-recording.mov" \
  --title "PDF preview hyperlinks trigger leave-page modal"

Or for a GitHub attachment:

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "https://github.com/user-attachments/assets/..." \
  --title "Slash menu loses selection after confirm"

Or for a local file:

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "/absolute/path/to/video.mov" \
  --title "Preview hyperlink exits workflow"

For auth-gated Linear uploads, the helper automatically retries with cookies from the local Linear desktop app on macOS. For private GitHub asset URLs, it retries with

GITHUB_TOKEN

GH_TOKEN

, or

gh auth token

when available.

针对每个相关视频运行一次辅助脚本：

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "https://uploads.linear.app/.../screen-recording.mov" \
  --title "PDF预览超链接触发离开页面弹窗"

针对GitHub附件的用法：

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "https://github.com/user-attachments/assets/..." \
  --title "斜杠菜单确认后丢失选中状态"

针对本地文件的用法：

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh \
  "/absolute/path/to/video.mov" \
  --title "预览超链接退出工作流"

对于需要权限验证的Linear上传文件，辅助脚本会自动尝试使用macOS本地Linear桌面应用中的Cookie进行重试。对于私有GitHub资产URL，若存在

GITHUB_TOKEN

、

GH_TOKEN

或

gh auth token

，脚本会使用这些凭据进行重试。

Use This When

使用场景

A GitHub or Linear issue, PR, or comment includes a screen recording.
An attachment URL points to
```
uploads.linear.app
```
.
An attachment URL points to a GitHub attachment or private GitHub asset host.
You need timeline-style transcript lines, not a vague summary.
You want the result in this exact XML shape:

xml

<video-transcripts>
<video-transcript title="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

GitHub或Linear的问题、PR（拉取请求）或评论中包含屏幕录制文件时
附件URL指向
```
uploads.linear.app
```
时
附件URL指向GitHub附件或私有GitHub资产托管服务时
您需要带时间轴的转录文本行，而非模糊的摘要时
您需要结果为以下精确XML格式时：

xml

<video-transcripts>
<video-transcript title="...">
[00:00] (...)
</video-transcript>
</video-transcripts>

Workflow

工作流程

Run the helper once for each relevant video.
Give each run a short, bug-focused
```
--title
```
.
For tracked work, the canonical shared cache should live in the tracker next to the evidence it describes.
If the video is in the issue or PR body, use a top-level tracker comment.
If the video is in a Linear comment, post the transcript cache as a reply to that specific comment.
If the video is in a GitHub issue or PR comment, use one dedicated top-level cache comment for that source comment's video set. GitHub has no replies, so keep cache comments separated by source container instead of merging unrelated comment videos together.
Cache comment or reply body should start with a transcript source link, then the timestamp lines:

[[Transcript](link to video or comment if not available)]
[00:00] (...)

When caching helper XML, strip the
```
<video-transcripts>
```
and
```
<video-transcript ...>
```
wrapper lines and paste only timestamp lines after the source link.
If there are multiple videos in the same source container, repeat the
```
[[Transcript](...)]
```
source link plus timestamp lines for each video.
Do not hand-write or paraphrase video behavior when the helper can run. Use the actual transcript output.
Link
```
[[Transcript](...)]
```
to the video URL when available. If the video URL is not available or is unstable, link to the source comment that contains the video.
For signed tracker-hosted URLs like
```
uploads.linear.app
```
, strip the query string so a new signature does not invalidate an otherwise valid cache entry.
Do not add decorative metadata like
```
title
```
to cached transcript entries unless a later workflow truly needs it.
Before re-transcribing for tracked work, match cache entries by source container first:
- one cache comment for issue or PR body videos
- one Linear reply per comment containing video(s)
- one dedicated GitHub cache comment per issue or PR comment containing video(s)
If the matching cache already covers the current normalized video keys for that source container, reuse it. Only transcribe missing or new video evidence.
Do not use
```
docs/
```
for raw tracker transcript cache. That is durable repo knowledge space, not raw issue evidence.
If you invoke this through
```
codex exec
```
, prefer
```
-o <file>
```
so the final XML is captured without CLI progress chatter.

针对每个相关视频运行一次辅助脚本。
为每次运行设置一个简短的、聚焦于问题的
```
--title
```
参数。
对于跟踪中的工作项，标准共享缓存应存放在跟踪器中，与它所描述的证据相邻。
如果视频位于问题或PR正文中，使用跟踪器的顶级评论。
如果视频位于Linear评论中，将转录缓存作为该特定评论的回复发布。
如果视频位于GitHub问题或PR评论中，为该源评论中的视频集使用一个专门的顶级缓存评论。GitHub不支持回复，因此请按源容器分隔缓存评论，不要合并无关评论中的视频。
缓存评论或回复的正文应先包含转录源链接，再加上时间戳行：

[[转录文本](视频或评论链接，若无法直接获取视频则链接评论)]
[00:00] (...)

缓存辅助脚本生成的XML时，去掉
```
<video-transcripts>
```
和
```
<video-transcript ...>
```
包装行，仅粘贴源链接后的时间戳行。
若同一源容器中有多个视频，为每个视频重复
```
[[转录文本](...)]
```
源链接加时间戳行的格式。
当辅助脚本可运行时，请勿手写或转述视频内容，应使用实际的转录输出。
若视频URL可用，将
```
[[转录文本](...)]
```
链接指向视频URL；若视频URL不可用或不稳定，则链接到包含该视频的源评论。
对于类似
```
uploads.linear.app
```
的签名跟踪器托管URL，去掉查询字符串，避免新签名使原本有效的缓存条目失效。
除非后续工作流确实需要，否则请勿为缓存的转录条目添加
```
title
```
等装饰性元数据。
为跟踪工作重新转录之前，先按源容器匹配缓存条目：
- 问题或PR正文中的视频对应一个缓存评论
- 包含视频的每个Linear评论对应一个回复
- 包含视频的每个GitHub问题或PR评论对应一个专门的顶级缓存评论
如果匹配的缓存已覆盖该源容器当前的标准化视频密钥，则复用该缓存。仅对缺失或新增的视频证据进行转录。
请勿将原始跟踪器转录缓存存放在
```
docs/
```
目录下，该目录是持久化的仓库知识空间，而非原始问题证据存储区。
如果通过
```
codex exec
```
调用本工具，建议使用
```
-o <file>
```
参数，以便捕获最终的XML内容，避免CLI进度信息干扰。

Output Contract

输出约定

Return XML, not Markdown.
Use one
```
[MM:SS] (...)
```
line per observed action or system response.
Quote visible UI text when legible.
Describe only visible actions, screen changes, and audible speech if present.
Do not invent hidden state, motives, or implementation details.
Prefer concise, high-signal lines over per-keystroke sludge.

返回XML格式，而非Markdown。
每个观察到的操作或系统响应对应一行
```
[MM:SS] (...)
```
格式的内容。
若可见UI文本清晰可辨，需加上引号。
仅描述可见操作、屏幕变化以及（若存在的）可听语音。
请勿臆测隐藏状态、动机或实现细节。
优先使用简洁、高信息量的内容，而非逐按键记录的冗余信息。

Model Strategy

模型策略

The helper defaults to

gemini-3.1-flash-lite-preview

for cost efficiency.

If that output is malformed, too thin, or obviously noisy, it retries with

gemini-3-flash-preview

For Gemini 3 models, the helper forces minimal thinking so output budget goes to the transcript instead of hidden reasoning.

Override with:

bash

VIDEO_TRANSCRIPTS_MODEL=gemini-3-flash-preview bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh ...

Or:

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh ... \
  --model gemini-2.5-flash

为了成本效益，辅助脚本默认使用

gemini-3.1-flash-lite-preview

模型。

若该模型的输出格式错误、内容过于简略或明显存在噪声，脚本会自动重试使用

gemini-3-flash-preview

模型。

对于Gemini 3系列模型，辅助脚本会强制减少模型的推理过程，让输出预算更多用于转录文本而非隐藏的推理步骤。

可通过以下方式覆盖默认模型：

bash

VIDEO_TRANSCRIPTS_MODEL=gemini-3-flash-preview bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh ...

或者：

bash

bash .agents/skills/video-transcripts/scripts/generate_video_transcript.sh ... \
  --model gemini-2.5-flash

Notes

注意事项

The helper accepts a local file path or remote URL.

For

uploads.linear.app

URLs, it first tries

LINEAR_COOKIE_HEADER

, then

LINEAR_COOKIES_DB

, then falls back to the local Linear desktop cookie store at

~/Library/Application Support/Linear/Cookies

For GitHub asset URLs, it first tries
```
GITHUB_TOKEN
```
, then
```
GH_TOKEN
```
, then
```
gh auth token
```
, then falls back to an unauthenticated download.
It looks for
```
GEMINI_API_KEY
```
, then
```
GOOGLE_API_KEY
```
.
If neither is set, it tries
```
~/.bash_profile
```
before failing.
Use
```
--debug-dir <dir>
```
when you want request and response artifacts saved.
Quality gate rejects obvious low-signal transcripts such as repeated partial typing runs and falls back automatically.

辅助脚本接受本地文件路径或远程URL。
对于
```
uploads.linear.app
```
URL，脚本会先尝试使用
```
LINEAR_COOKIE_HEADER
```
，再尝试
```
LINEAR_COOKIES_DB
```
，最后 fallback 到本地Linear桌面应用的Cookie存储目录
```
~/Library/Application Support/Linear/Cookies
```
。
对于GitHub资产URL，脚本会先尝试使用
```
GITHUB_TOKEN
```
，再尝试
```
GH_TOKEN
```
，接着尝试
```
gh auth token
```
，最后 fallback 到未认证下载。
脚本会查找
```
GEMINI_API_KEY
```
，若未找到则查找
```
GOOGLE_API_KEY
```
。
若两个密钥均未设置，脚本会尝试从
```
~/.bash_profile
```
中读取，若仍失败则终止运行。
若需要保存请求和响应 artifacts，可使用
```
--debug-dir <dir>
```
参数。
质量校验会自动拒绝明显低信息量的转录文本（如重复的部分打字记录），并自动 fallback 到其他模型重试。