Takazudo Modular Docs

Type to search...

to open search from anywhere

YouTube Guide Writer — Workflow Reference

YouTube Guide Writer — Workflow Reference

Detailed reference for the youtube-guide-writer skill. Covers article types, image conventions, YouTube embed patterns, manual integration, and writing best practices.

Default Branch for New WIP Drafts

New WIP article drafts default to base/wip-articles, NOT main. This is a long-lived accumulation branch — drafts land there, finalized episodes get individual PRs to main.

Source of truth: “WIP Article Base Branch” section in the repo-root CLAUDE.md. Writing guide: doc/src/content/docs/writing/guide-article-writing.md.

Article Types

video-guide (default)

The article follows the video timeline. Each section corresponds to a segment of the video. Best when:

  • The video IS the primary content (official tutorials, walkthroughs)
  • The video has clear chapter structure
  • Readers benefit from following along with the video

Structure pattern:

Introduction → YouTube embed → TOC → [Section per video segment] → Tips → Outro

Example: The OXI ONE MKII guide series (EP.1-EP.6) follows official tutorial videos. Each episode maps to one tutorial video, with sections mirroring the video’s topics.

product-explanation

The article is organized by product features, using the product manual as the structural backbone. Video captures serve as visual evidence. Best when:

  • A comprehensive product manual exists (in zmanuals)
  • The video demonstrates features covered in the manual
  • Readers need reference-style content organized by feature

Structure pattern:

Introduction → YouTube embed → TOC → [Section per feature/chapter] → Tips → Outro

Each feature section includes:

  • Manual-sourced technical details (parameter ranges, signal specs)
  • Video capture showing the feature in action
  • Timestamp link to the video demonstration

Image Workflow

Two-phase image approach

Images go through two phases:

  1. Draft phase — captures copied to public/images/temp-article-caps/ and referenced via <img src="/images/temp-article-caps/..." alt="..." />. This lets you preview the article immediately during pnpm dev
  2. Finalization phase — when the article is approved, images move to imgs/ for R2 pipeline processing, and <img> tags are replaced with <ArticleImage>

Auto-selection from captures

Never use placeholder images. Always auto-select from the captured frames:

  1. Read transcript.json — each entry has start (seconds) and text
  2. For each article section, identify the timestamp range it covers
  3. Convert the target timestamp to HH-MM-SS format to find the matching capture:
    • 42.5 seconds → capture-00-00-42.jpg
    • 185 seconds → capture-00-03-04.jpg (round to nearest even second)
  4. Select 10-15 captures per article (1 per 2-3 paragraphs)
  5. Copy to public/images/temp-article-caps/ with descriptive names

Temp image directory convention

public/images/temp-article-caps/
├── oxi-cap-ep1-front-panel.jpg
├── oxi-cap-ep1-mono-mode.jpg
├── oxi-cap-ep1-step-edit.jpg
└── ...
  • This directory is for draft articles only
  • Files are served at /images/temp-article-caps/ during dev
  • Do NOT commit these to git — they are temporary staging
  • When finalizing, move originals to imgs/ and run pnpm convimgs:upload

Slug naming format

{product-prefix}-cap-ep{N}-{feature-name}-{HH-MM-SS}
  • {product-prefix}: Short product identifier (e.g., oxi, disting, squid)
  • cap: Indicates this is a video capture
  • ep{N}: Episode number
  • {feature-name}: Descriptive kebab-case name of what the image shows
  • {HH-MM-SS}: Required. The cover frame’s timestamp in the source video, copied verbatim from the picked capture-HH-MM-SS.jpg filename. The timestamp is encoded into the slug so the cover-frame time is permanently recoverable from the filename even if the ?t=N URL param on <YoutubeAt> is later corrupted (a guess, a copy-paste mistake, a later edit). Without it, drift between URL and cover cannot be detected. The numeric ?t=N MUST equal HH*3600 + MM*60 + SS.

Examples

oxi-cap-ep1-front-panel-00-00-25
oxi-cap-ep1-mono-mode-00-02-10
oxi-cap-ep2-poly-grid-00-04-20
oxi-cap-ep3-chord-voicing-00-05-50
disting-cap-ep1-algorithm-select-00-01-30
squid-cap-ep2-cv-routing-00-07-23

Legacy slugs (pre-rule)

Articles finalized before this rule (e.g., the original oxi-cap-ep1-* set without timestamp suffix, the original SHIK EP.1 set) keep their existing slugs — do NOT rename, since R2 paths and metadata-db.json records are stable. The timestamp suffix rule applies only to articles being finalized fresh.

Thumbnail and OGP

For the first episode in a series, consider whether to create a dedicated OGP image or reuse an existing product promo image:

  • Shared series thumbnail: Use the product’s promo image with __og suffix (e.g., oxi-mk2-promo-group-bkbg__og)
  • Per-episode OGP: Create {product}-cap-ep{N}-hero__og from a compelling capture

Set imgThumb in frontmatter to the chosen slug.

YouTube Embed Patterns

Full video embed (at top of article)

<Youtube url="https://youtu.be/VIDEO_ID" />

Timestamp-specific embed (within sections)

<Youtube url="https://youtu.be/VIDEO_ID?t=123" />

The t parameter is in seconds. Convert from video timestamp:

  • 2:30 → t=150
  • 10:45 → t=645
  • 1:02:30 → t=3750

When to use timestamp embeds

  • When a section describes something that’s demonstrated at a specific point in the video
  • For complex operations that are easier to understand by watching
  • For before/after demonstrations
  • Don’t overuse — one timestamp embed per major section is usually enough

Integration with zmanuals

Finding manuals

Product manuals are stored in the zmanuals repo:

~/repos/zp/zmanuals/public/{product-slug}/data/

Each manual directory contains:

  • pages-ja.json — Japanese translated manual content
  • pages-en.json — English translated manual content
  • manifest.json — manual metadata (title, brand, page count, etc.)
  • ../pages/page-NNN.png — page images

Source PDFs are at ~/repos/zp/zmanuals/manual-pdf/{product-slug}/.

Using manual content

  • Manual content provides authoritative technical details
  • Use it to verify accuracy of information from the video
  • Extract specific parameter ranges, signal specs, and procedures
  • Always restructure into original prose — never copy verbatim
  • Use the /refer-another-project zmanuals pattern for safe cross-repo reference

Info boxes for manual details

When citing specific technical details from the manual, consider using an info box:

<InfoBox>
マニュアルによると、CV出力の電圧範囲は0V〜+5Vで、12ビットの分解能を持っています。
</InfoBox>

Article Voice: Video Writedown Style

Guide articles use the video writedown voice — a guide-article-specific application of the project-wide AI writing rule. The AI writes facts, technical explanations, and operation descriptions. Emotional commentary is added by the human author later.

Project-wide base rule: .claude/skills/_shared/writing-voice.md is the authoritative “AI writes facts, human adds emotion” rule for ALL writing skills in this repo. The 4 anti-patterns below are the worked-example version for guide articles, and are fully consistent with the project-wide rule. Read the shared file first if you have not already.

See doc/src/content/docs/writing/guide-article-writing.md for the full guide-article spec (frontmatter, sections, naming conventions, etc.).

Voice spectrum

Too dry (manual)  ◄──────  ★ TARGET  ──────►  Too emotional (blog)
Pattern A                  Preferred            Pattern B/D

The 4 anti-patterns (from EP.7 A/B testing)

These patterns were tested and rejected. Excerpts preserved here for reference so the AI can recognize and avoid them.

Pattern A: Technical Reference (too dry)

Reads like a spec sheet or 1-page manual. Facts only, no context, no flow.

## ページナビゲーション

シーケンスは8ページ構成、各16ステップ、合計128ステップ。

### 基本ページ（ステップ1〜64）

ページボタンで直接アクセス。ボタンの数字はページの最終ステップ番号を表す。

| ボタン | 表示ステップ |
|--------|-------------|
| **16** | 1〜16 |
| **32** | 17〜32 |

Problem: Proper for a printed quick-reference card, but too dry for a web article. No connecting text, no explanation of why things work that way. Readers disengage.

Pattern B: Emotional Narrative (too much feeling)

First-person journey with invented emotions and personal anecdotes.

128ステップのシーケンスを組んでいて、途中で「あれ、今どこにいるんだ？」と
なったことはありませんか？ 自分も最初はそうでした。OXI ONE MKIIは最大128
ステップという長大なシーケンスを扱えるのですが、その全体像を把握しながら
作業するのは、最初はなかなか大変です。

でも、ページナビゲーションの仕組みを理解して、パターン長の設定やコピー&ペースト、
Follow機能を使いこなせるようになると、128ステップのシーケンスでも迷子に
ならなくなりました。

Problem: AI invents feelings (“自分も最初はそうでした”) that the human author didn’t experience. Reads as someone else’s diary. The emotional layer should be added by the human, not the AI.

Pattern C: Step-by-Step Tutorial (wrong format)

Hands-on workshop style with “やってみよう” sections and confirmation checkpoints.

## やってみよう: ページナビゲーション

1. まず、OXI ONE MKIIの電源を入れ、シーケンサー画面を表示します
2. **16**のページボタンを押してください。ステップ1〜16が表示されます
3. 次に**32**のボタンを押します。ステップ17〜32に切り替わります

**確認ポイント:** ボタンに書かれた数字は、そのページの**最後のステップ番号**です。
**32**ボタンを押したとき、ステップ17〜32が表示されていますか？

Problem: Assumes workshop context. Good for actual hands-on training materials, but web articles are read passively. The “やってみましょう” / “確認してください” format doesn’t fit.

Pattern D: Casual Conversation (too rough)

Talking-to-a-friend style with colloquial expressions.

で、ページボタンが4つあるんだけど、これがなかなか賢い。ボタンに書いてある
数字は、そのページの最後のステップ番号。**32**を押せばステップ17〜32が
出てくる、みたいな感じ。

つまり8ページ分のナビゲーションをたった4つのボタンでカバーしてるってこと。
なかなか賢い設計。

Problem: Too casual for a shop’s public content. Some readers dislike this style — it assumes friendship that doesn’t exist. OK for podcast notes or friend-to-friend sharing, not for official product guides.

The preferred voice (video writedown)

Balanced prose derived from video content. Not a transcript dump, not an essay.

最初の4ページ（ステップ1〜64）には、**ページボタン**を使って直接アクセス
できます。ボタンに書かれている数字は、そのページの最後のステップ番号を
表しています。例えば**32**のボタンを押すと、ステップ17〜32が表示されます。

後半の4ページ（ステップ65〜128）にアクセスするには、同じページボタンを
**もう一度押します**。ボタンがシアン色に変わり、拡張ページに入ったことを
示します。

Why this works: Explains what it does, how to use it, and what visual feedback to expect. No invented emotions, no workshop commands, no friend-talk. Professional but readable. The reader gets all the information they need to understand the feature.

Writing Best Practices

From guide-article-writing.md

  • Transcript → prose: Spoken language must be restructured. Direct transcription reads poorly as written text.
  • Image rhythm: Insert a visual element (image or component) every 2-3 paragraphs. Long text-only sections cause readers to disengage.
  • Bold emphasis: Use **bold** for button names, parameter names, and mode names. Example: **Shiftボタン**を押しながら**Encoder 1**を回す
  • Specific values: “Set Density to 80%-100%” not “Set Density high”
  • Explanatory tone: Not textbook-like, but as if an experienced user is explaining
  • Practical tips: Show concrete usage patterns, not just theory

Section structure

Each body section should follow this general pattern:

## Section Title

Brief introduction to what this section covers and why it matters.

<img src="/images/temp-article-caps/product-cap-epN-feature.jpg" alt="Caption describing the image" />

Detailed explanation with **bold parameter names** and specific values.

Another paragraph continuing the explanation...

<Youtube url="https://youtu.be/VIDEO_ID?t=180" />

Follow-up explanation after the video reference. Practical tips for this feature.

Note: During draft phase, use <img> tags with temp capture paths. When the article is finalized and images are processed through R2, replace with <ArticleImage slug="..." caption="..." />.

Cross-episode consistency

  • Use the same terminology across all episodes
  • Maintain consistent formatting for section introductions and outros
  • Link to other episodes when cross-references exist: [EP.1で解説した基本操作](/notes/product-guide-ep1/)

~/youtube-dl/ Directory Structure

After downloading and capturing, the directory looks like:

~/youtube-dl/
└── 20260326-VIDEO_ID-video-title/
    ├── video/
    │   └── video-title.mp4
    ├── metadata/
    │   └── metadata.json              # Title, description, duration, etc.
    ├── transcript/
    │   └── transcript.json            # Array of {start, duration, text}
    └── captures/
        ├── capture-00-00-00.jpg       # t=0s
        ├── capture-00-00-02.jpg       # t=2s
        ├── capture-00-00-04.jpg       # t=4s
        ├── capture-00-01-30.jpg       # t=90s
        └── ...                        # At 2-sec intervals, HH-MM-SS format

With 2-second intervals, a 10-minute video produces ~300 frames. Capture filenames use HH-MM-SS timestamp format, making it easy to match transcript timestamps:

  • Transcript start: 42.5 → capture-00-00-42.jpg
  • Transcript start: 150.0 → capture-00-02-30.jpg
  • Transcript start: 645.0 → capture-00-10-44.jpg (nearest even second)

Transcript JSON format

[
  { "start": 0.0, "duration": 3.5, "text": "Welcome to the tutorial" },
  { "start": 3.5, "duration": 4.2, "text": "Today we'll look at..." },
  ...
]

Common Custom Components

Temp capture image (draft phase)

<img src="/images/temp-article-caps/product-cap-epN-feature.jpg" alt="Description of what's shown" />
  • Used during draft/writing phase with auto-selected captures
  • Files live in public/images/temp-article-caps/
  • Replaced with <ArticleImage> during finalization

ArticleImage (finalized)

<ArticleImage slug="product-cap-epN-feature" caption="Description of what's shown" />
  • slug: Must match a processed image slug in metadata-db.json
  • caption: Japanese description of the image content
  • Used after images are processed through R2 pipeline

Youtube

<Youtube url="https://youtu.be/VIDEO_ID" />
<Youtube url="https://youtu.be/VIDEO_ID?t=123" />

RelatedProducts

<RelatedProducts ids={['product-id-1', 'product-id-2']} />

Product IDs come from src/data/product-master-data.mjs.

InfoBox

<InfoBox>
Additional context or technical details here.
</InfoBox>

Product-specific custom components

Some guide series benefit from custom explanation components. For example, the OXI ONE MKII series uses <OxiGridFigure> to visualize sequencer grid states. Consider whether the product you’re writing about would benefit from a similar component. If so, note it in the plan but don’t create it unilaterally — discuss with the user first.

Articles Without Transcripts

Some videos lack transcripts — demo videos without narration (e.g., ADDAC215), live performances, or videos in unsupported languages. The workflow still applies with these adaptations:

Strategy

  1. Still download full video + 2-sec captures — captures are the essential visual index regardless of whether a transcript exists
  2. Watch the video via captures — scrub through the captured frames to understand what’s being demonstrated at each point
  3. Use product data as the structural backbone — pull from product-master-data.mjs, product manuals (zmanuals), and product pages to organize the article by features
  4. Match captures to features — instead of transcript timestamps, identify which captures show each feature being demonstrated
  5. Select 10-15 captures as with transcript-based articles

Key differences

  • Article structure comes from the product, not the video timeline
  • Image selection is manual (visual inspection of captures) rather than timestamp-matched
  • More emphasis on product data and manual content for accuracy
  • YouTube embeds still useful for “watch this section” references

Guide Series Registration

guide-series.mjs structure

Each series entry in src/data/guide-series.mjs:

{
  slug: 'product-guide',           // URL-safe identifier
  name: 'Product Nameガイド',       // Japanese display name
  nameEn: 'Product Name Guide',    // English display name
  description: '...',              // Japanese description
  descriptionEn: '...',           // English description
  thumbSlug: 'product-thumb__og', // Thumbnail image slug
  articleSlugs: [                  // Ordered array of article slugs
    'product-guide-ep1',
    'product-guide-ep2',
  ],
}

Adding an episode to an existing series

Append the new slug to the articleSlugs array:

articleSlugs: [
  'product-guide-ep1',
  'product-guide-ep2',
  'product-guide-ep3', // ← new episode
],

Creating a new series

Add a new object to the guideSeries array. Match the frontmatter categories of the articles to the series slug.

Frontmatter ↔ series connection

The article’s frontmatter categories array must include the series slug:

categories:
  - product-guide       # ← matches guide-series.mjs slug
  - guide

Guide Series Conventions

Additional rules that apply when an article is part of a guide series (i.e., when --series is specified).

No Discord invitation text

Do NOT include Discord invitation text or links in guide series articles. Repeating Discord guidance in every episode is verbose — omit it entirely.

Instead of inline manual translation text in the introduction, use the <ProductDetailManualNav> component placed before the YouTube embed:

<ProductDetailManualNav slug="oxi-coral" />

Match slug to the product (e.g., "oxi-coral", "disting-mk4"). This renders a standardized manual navigation block and avoids duplicated prose across episodes.

No “前回までの記事” section

Do NOT include a “前回までの記事” (previous articles) list. The series navigation component handles cross-episode linking automatically — a manual list is redundant.

Pre-Publish Checklist

Draft phase checklist

  • All temp captures copied to public/images/temp-article-caps/
  • All <img> tags point to valid temp capture files
  • YouTube embeds load correctly (valid video IDs and timestamps)
  • Frontmatter tags and categories are correct
  • Guide series data updated if applicable
  • Article renders correctly on mobile and desktop
  • pnpm check passes
  • Writing style rules followed (bold emphasis, specific values, image rhythm)

Finalization (when article is approved)

For the full finalization flow, invoke Step 10 in the youtube-guide-writer skill:

/l-youtube-guide-writer --finalize <mdx-path>

Step 10 handles: slug derivation (with confirmation), source file staging, R2 upload, MDX rewriting (JA + EN sibling), and verification. Always confirm the slug mapping before the skill proceeds.

After finalization, verify manually:

  • Article renders correctly at the expected URL (pnpm dev smoke test)
  • All images load (no broken image placeholders)
  • pnpm check:capture-wip passes (no WIP components remain in the article)
  • OGP image is set (imgThumb pointing to a slug with __og suffix)
  • pnpm check passes (type check, lint, format)