z-video-study-webpage-qwen

Qwen multimodal video learning webpage

Truly break a video apart for learning: first extract audio and transcribe it into full text, then extract frames at key timestamps, and use the DashScope OpenAI-compatible API's qwen3.7-plus to understand each segment, and finally generate a learning summary webpage. The webpage follows the current study-summary.html 's visual template: beige paper, cards, timeline, risk matrix, local video player, keyframe image-text cards.

Applicable scenarios

The user provides a local MP4 and requests a complete understanding of the video and a learning summary webpage.
The user provides a YouTube / Bilibili / mainstream platform link and requests understanding after downloading; first call z-video-downloader to download, then use this skill to analyze the local MP4.
The user explicitly requests that "key knowledge points must match the correct visuals"; prioritize using this skill.
The user mentions DashScope, Qwen multimodal,qwen3.7-plus, or OpenAI-compatible base_url; also use this skill.

Security conventions

The API Key is only read from environment variables; the default variable name is:DASHSCOPE_API_KEY。
Do not write the user-provided key into SKILL.md, scripts, reports, HTML, terminal logs, or the final reply.
Default base URL:https://dashscope.aliyuncs.com/compatible-mode/v1。
Default model:qwen3.7-plus. If the API returns that the model does not exist, remind the user to use --model to change it to an actually available model name.

Input and output

Input can be:

Local MP4:/path/to/video.mp4
Directory containing the downloaded video
Platform link: first use z-video-downloader to obtain the local MP4

Default output is in the same directory as the video or a specified directory:

study-qwen/
├── study-summary-qwen.html        # 最终学习网页
├── qwen-analysis.json             # 模型结构化结果
├── storyboard.json                # 关键帧清单
├── transcript.txt                 # 完整转录文本，若成功
├── transcript.json                # 带时间戳转录，若成功
├── assets/
│   ├── frame-001.jpg
│   ├── frame-002.jpg
│   └── ...
└── run-report.json

Recommended commands

export DASHSCOPE_API_KEY="放在你本机环境里，不要写进文件"

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-study-webpage-qwen/scripts/qwen_video_study.py \
  --video "/path/to/video.mp4" \
  --title "视频主题" \
  --out-dir "/path/to/output/study-qwen" \
  --model "qwen3.7-plus"

If there is already a subtitle or transcript:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-study-webpage-qwen/scripts/qwen_video_study.py \
  --video "/path/to/video.mp4" \
  --transcript "/path/to/transcript.txt" \
  --title "视频主题" \
  --out-dir "/path/to/output/study-qwen"

Only verify frame extraction and the webpage template, without calling the model:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-study-webpage-qwen/scripts/qwen_video_study.py \
  --video "/path/to/video.mp4" \
  --title "视频主题" \
  --out-dir "/path/to/output/study-qwen" \
  --mock-analysis

Execution workflow

Confirm the local video path
- If the user provided a URL, first use z-video-downloader to download.
- After finding the actual MP4, execute this skill.
Extract keyframes
- By default, extract 12 segments, with 1-3 representative frames per segment.
- Write each image into storyboard.json; fields include frame_id、timestamp、time_label、path。
- These frame_id are the sole basis for subsequently binding knowledge points to visuals.
Full transcription
- Prioritize using the user-provided --transcript。
- When there is no transcript, the script attempts to transcribe the audio using the local Whisper.
- If Whisper is unavailable, continue with visual analysis, but the report must indicate "missing full-text transcription; conclusions rely more on visuals and existing title information".
Qwen multimodal segment-by-segment analysis
- For each segment, send: that segment's transcript, time range, and corresponding keyframe images.
- Prompt the model to output JSON: segment topic, key knowledge points, evidence, visual binding, and information to be confirmed.
- Key knowledge points must cite actually existing frame_id。
Global learning structure synthesis
- Call Qwen once more to synthesize the segmentation results into:
  - 30-second overview
  - Learning map
  - Key knowledge points × correct visuals
  - Timeline
  - Risk / opportunity matrix
  - Review questions
  - Action checklist
- If the model provides a nonexistent frame_id, the script automatically falls back to the first image in the same segment and records the correction in the JSON.
Render HTML
- Follow the visual language of the current learning webpage template.
- There must be a local video player at the top.
- Each key knowledge point card must include a local frame image.
- The HTML must reference only local images and local videos.
Final check
- Verify that all local media paths in the HTML exist.
- Verify that qwen-analysis.json can be parsed.
- Check that the API key has not been written into any output file.
- If the task produces .md and it contains external image links, then call 1-upload-images-to-picgoaccording to the project rules; this skill produces HTML by default, so no image hosting is needed.

Quality standards

Do not give only a vague summary based on the video title.
Do not just capture a few images and then write vague conclusions.
Key knowledge points must come from the transcript, the visuals, or cross-validation of both.
Each key knowledge point must have a corresponding visual: the image should intuitively show the person, product, diagram, scene, or risk theme.
Mark uncertain content as "to be verified"; do not disguise it as fact.

Test

After editing the script, run:

/Users/zz/miniconda3/bin/python3 -m py_compile \
  .agent/skills/z-video-study-webpage-qwen/scripts/qwen_video_study.py \
  .agent/skills/z-video-study-webpage-qwen/tests/test_qwen_video_study.py

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-study-webpage-qwen/tests/test_qwen_video_study.py