🎬 SpDL-Editor

English | 日本語

---

📖 English

Version: 3.1.6

A VS Code extension for screenplay writing for films, anime, voice dramas, and more. Manage professional scenarios with a hierarchical structure: Sequence → Scene → Cut.

SpDL (Screenplay) Editor supports creating new scenarios and adding templates, allowing you to easily add "Sequences," "Scenes," and "Cuts" structurally. The preview feature supports three formats: vertical (traditional screenplay), horizontal (modern), and storyboard paper, allowing you to instantly check your content.

With the newly added DOM structure display feature, you can view the hierarchical structure of your scenario in the sidebar at a glance and jump to any position with one click. This enables efficient navigation even for long scenarios.

Additionally, you can count total duration and dialogue character count with range specification, which is useful for production progress management. Furthermore, you can export in HTML format (vertical, horizontal, storyboard), as well as CSV markers for Premiere Pro and FCPXML files for Final Cut Pro. This realizes a seamless workflow from writing to editing.

SpDL (Screenplay Description Language) is a markup language designed to structure scenarios for films, anime, voice dramas, etc., while allowing humans to intuitively write in plain text. SpDL (Screenplay) Editor is based on SpDL.

Author's Site

🎯 Requires "YAML by Red Hat" Extension

Please install "YAML by Red Hat" in addition to this extension. "YAML by Red Hat" provides YAML error checking, code highlighting, and auto-completion features.

🚀 Command List

• Open Command Palette with Ctrl + Shift + P
• Or right-click to open context menu

Note: If there are YAML syntax errors, the structure check will not proceed and will stop. Most errors in web preview can be detected in advance with this structure check. This command can also be executed from the right-click menu of YAML files.

Command
sp: New File
sp: Add Template
sp: Add Sequence
sp: Add Scene
sp: Add Cut
sp: Preview (Vertical/Screenplay, Horizontal/Modern, Storyboard)
sp: Flow Diagram (Choices)
sp: Open AI Scenario Instructions
sp: Count Total Duration (with range selection)
sp: Count Dialogue Characters (with range selection)
sp: Export HTML (Vertical/Screenplay, Horizontal/Modern, Storyboard)
sp: Export CSV Markers (Premiere Pro)
sp: Export FcpXml (Final Cut Pro)

🤖 AI Scenario Writing Guide

If you want an AI assistant to generate SpDL YAML scenarios, see AI_SCENARIO_INSTRUCTIONS.md.

📁 Project / Multi-Scenario (Multi-File)

Use this mode when one title is split into multiple YAML files (for example: prologue, chapters, route branches, endings) and you still want to manage/export it as one project.

Recommended workflow:

• Open the entry file (usually main.yml).
• Run sp: Set Project Root (the project root becomes the entry file's folder).
• Run sp: Validate Links after editing branch links, renaming files, or moving folders (basic validation).
• Run sp: Generate Project HTML to export all .yml/.yaml under the root while keeping the folder structure.

Multi-file br_link supports relative file paths and anchors. Examples:

• Same file anchor: #start_adventure
• Same folder file: ./prologue.yml#opening
• Child folder file: chapter1/village.yml#center
• Parent folder file: ../main.yml#start_adventure

Notes:

• br_link paths are resolved relative to the YAML file that contains the link.
• During project HTML export, internal YAML links are converted to relative .html links.
• Non-main pages get a "Back to Main" navigation bar automatically.
• Keeping one stable entry file (main.yml) makes project navigation and re-export easier.

Sample project: templates/multifile-sample/ (includes main.yml, prologue.yml, chapter1/, chapter2/, endings/).

🆕 Structure Display & Navigation Features

• DOM Structure Display: A "Scenario Structure" view is added to the sidebar, visually displaying the hierarchical structure of Sequences, Scenes, and Cuts
• One-Click Jump: Click on a Scene or Cut in the structure display to quickly navigate to that location
• Refresh Structure: After editing a file, you can update the structure display from the right-click menu

✅ Scenario Structure Validation

The sp: YAML Syntax + Structure Check command performs validation in two stages:

🔹 1. YAML Syntax Check (Basic Grammar)

Checks if the YAML format is correct. Example: Indentation errors, unclosed strings, incorrect colons or lists, etc.

• If there are errors: ❌ YAML syntax error: ...

🔹 2. SpDL Structure (Scenario Structure)

Validates the structure based on SpDL specifications: Note: The following structure alone will cause an error.

sequences: <------------ Sequence
  - id: 1
    
    scenes: <------------ Scene
      - id: 1

        cuts: <------------ Cut
          - id: 1

• If there are errors: ⚠️ SpDL structure error: Please check if the structure of sequences > scenes > cuts is correct.

• If both are correct: ✅ YAML syntax + SpDL structure are all valid

---

📖 日本語

バージョン: 3.1.6

映画・アニメ・ボイスドラマ・その他なんでも、シナリオ作成支援VSCode拡張機能 シーケンス → シーン → カット の階層構造で、プロフェッショナルなシナリオ管理が可能になります。

SpDL (Screenplay) Editorは、シナリオの新規作成やテンプレート追加に対応しており、構造的に「シーケンス」「シーン」「カット」を簡単に追加できます。プレビュー機能では、縦書きのシナリオ形式、横書きのモダン形式、絵コンテ用紙形式の3種類に対応し、内容を即座に確認できます。

新たに追加されたDOM構造表示機能により、サイドバーでシナリオの階層構造を一目で確認し、任意の位置にワンクリックでジャンプできるようになりました。これにより、長いシナリオでも効率的にナビゲーションできます。

また、総尺やセリフの文字数を範囲指定してカウントする機能もあり、制作中の進行管理や目安確認に役立ちます。さらに、HTMLによる縦書き・横書き・絵コンテ形式で書き出せるほか、Premiere Pro用のCSVマーカー、Final Cut Pro用のFCPXMLファイルとしても出力可能です。 これにより、執筆から編集作業まで、シームレスなワークフローを実現します。

SpDL（Screenplay Description Language:シナリオ記述言語）は、映画・アニメ・ボイスドラマなどのシナリオを構造化しつつ、人間がプレーンテキストで直感的に記述できることを目的とした記述言語です。 SpDL (Screenplay) Editor は SpDLをベースとしています。

作者サイト

🎯要「YAML by Red Hat」のインストール

本拡張機能に加えて「YAML by Red Hat」のインストールを行ってください。 「YAML by Red Hat」は、YAMLのエラーチェックやコードハイライト、補完機能を持ちます。

🚀 コマンド一覧

• Ctrl + Shift + P でコマンドパレットを開く
• または、マウス右ボタンでコンテクストメニューを開く

🔸注意

• YAML構文エラーがある場合、構造チェックには進まず停止します。
• Webプレビューで出るエラーの大半はこの構造チェックで事前検出できます。
• このコマンドは YAMLファイルの右クリックメニューからも実行できます。

コマンド
sp:新規ファイル
sp:テンプレート追加
sp:シーケンス追加
sp:シーン追加
sp:カット追加
sp:プレビュー（縦書き（シナリオ）, 横書き（モダン）, 絵コンテ用紙）
sp:分岐フロー図（選択肢）
sp:AIシナリオ作成ガイドを開く
sp:総尺カウント（範囲指定対応）
sp:セリフ文字数カウント（範囲指定対応）
sp:HTML書き出し（縦書き（シナリオ）, 横書き（モダン）, 絵コンテ用紙）
sp:CSVマーカー書き出し（Premiere Pro）
sp:FcpXml書き出し（Final Cut Pro）

🤖 AI向けシナリオ作成ガイド

AIがSpDL（YAML）でシナリオを書けるようにするための手引きは AI_SCENARIO_INSTRUCTIONS.md を参照してください。

📁 プロジェクト / マルチシナリオ（マルチファイル）

この機能は、1つの作品を複数のYAML（プロローグ、章ごと、分岐ルート、エンディングなど）に分割して管理しつつ、プロジェクトとしてまとめて出力したいときに使います。

おすすめの手順:

• 入口になるファイル（通常は main.yml）を開く
• sp: プロジェクトルート設定 を実行（そのファイルのフォルダがルート）
• ファイル名変更・フォルダ移動・分岐リンク編集のあとに sp: リンク検証 を実行（基本的な検証）
• sp: プロジェクト全体HTML生成 でルート配下の .yml/.yaml をフォルダ構成のままHTML出力

マルチファイルの br_link は、相対パス + アンカー指定に対応しています。例:

• 同一ファイル内: #start_adventure
• 同じフォルダ: ./prologue.yml#opening
• 下位フォルダ: chapter1/village.yml#center
• 上位フォルダ: ../main.yml#start_adventure

補足:

• br_link の相対パスは、そのリンクを書いたYAMLファイル基準で解決されます。
• プロジェクトHTML生成時に、内部のYAMLリンクは .html の相対リンクへ変換されます。
• メイン以外のページには「メインに戻る」ナビゲーションが自動で追加されます。
• main.yml のような入口ファイルを固定すると、再出力や運用が安定します。

サンプル: templates/multifile-sample/（main.yml, prologue.yml, chapter1/, chapter2/, endings/）

🆕 構造表示・ナビゲーション機能

• DOM構造表示: サイドバーに「シナリオ構造」ビューが追加され、シーケンス・シーン・カットの階層構造が視覚的に表示されます
• ワンクリックジャンプ: 構造表示からシーン・カットをクリックするだけで、該当箇所に素早く移動できます
• 構造の再表示: ファイルを編集した際、右クリックメニューから構造表示を更新できます

✅ シナリオ構造のチェックについて

sp: YAML構文＋構造チェック コマンドでは、以下の2段階の検証が実行されます。

🔹 1. YAML構文チェック（基本文法）

YAML形式として正しいかどうかを確認します。
例：インデントミス、文字列の閉じ忘れ、コロンやリストの誤記など

• エラーがある場合：
  ❌ YAML構文エラー: ...

🔹 2. SpDL構造（シナリオ構造）

SpDL仕様に基づき、次のような構造が適切かを検証します： 注）以下の記述のみではエラーとなります。

sequences: <------------ シーケンス
  - id: 1
    
    scenes: <------------ シーン
      - id: 1

        cuts: <------------ カット
          - id: 1

• エラーがある場合：
  ⚠️ SpDL構造エラー: sequences > scenes > cuts の構造が正しいか確認してください。

• 両方正しい場合：
  ✅ YAML構文 + SpDL構造ともに正常です

🎥 デモ動画

---

❓ FAQ

• Q: ファイル名は？
  • A: xxxx.sp.yml 形式で保存してください。

---

📝 主要フィールド一覧（完全版）

フィールド	日本語訳	説明
title	作品タイトル	シナリオ全体のタイトル
authors	著者リスト	シナリオの著者名（複数可）
created_at	作成日	シナリオが作成された日付（ISO形式）
updated_at	更新日	最終更新された日付（ISO形式）
version	バージョン	シナリオのバージョン番号
description	説明	流れ、場面、カットの簡単な説明　改行による文章の記述が可能
repository	リポジトリURL	最新版が格納されているGitHub等のURL
sequences	シーケンス	物語の流れの単位、複数シーンをまとめる
name	名前	シーケンス名・シーン名・カット名に使用
scenes	シーンリスト	シーケンス内に含まれる場面のリスト
id	ID	一意にシーンやカットを識別する番号
duration	時間（秒）	シーンまたはカットの再生時間（秒単位、null可）
time_of_day	時間帯	朝、昼、夕方、夜など場面の時間設定
se	サウンドエフェクト	効果音（例：BGM、環境音）
actors	登場人物リスト	シーン内で登場するキャラクター一覧
cuts	カットリスト	シーン内を構成するショットのリスト
camera	カメラ設定	ショットにおけるカメラのアングル・動き
action	動作	キャラクターやカメラの動作説明
dialogue	セリフリスト	セリフの配列（speakerとtextを持つ）
speaker	セリフの話者	dialogue内でセリフを話すキャラクター
text	セリフ本文	実際に話されるセリフ内容
transition	トランジション	カット間の映像切替効果（フェード、オーバーラップなど）

---

シナリオ構文フィールド＋記述ルール）

基本情報フィールド

フィールド	日本語訳	説明
title	作品タイトル	シナリオ全体のタイトル
authors	著者リスト	著者名（複数可、リスト形式）
created_at	作成日	ISO形式日付（例: 2025-05-14）
updated_at	更新日	最終更新日（任意）
version	バージョン	バージョン番号（例: "1.0"）
description	説明	シナリオの概要説明
repository	リポジトリURL	GitHubなどのURL

🔸 authors の記述例

✅ 正しい例：

authors:
  - "伊丹シゲユキ"
  - "山田花子"

❌ 間違い例（カンマ区切り）：

authors: "伊丹シゲユキ, 山田花子"

---

🔸 description の記述例

✅ description は複数行の改行に対応しています　 :

• 1行文字列は " " を使って記述

    description: "朝日のまぶしさに目をそむけて"

• 複数行文字列は | を使って記述 改行による記述は、そのままプレビューに反映されます。

    description: |
      朝日のまぶしさに目をそむけて歩く雄太は、
      走る自転車を左右に避けながら、
      器用に歩いていた。

---

構成フィールド

フィールド	日本語訳	説明
sequences	シーケンス	複数のシーンをまとめる単位（リスト）
name	名前	各構成要素の名前（シーケンス・シーン・カットなど）
scenes	シーンリスト	シーケンスに含まれる場面群（リスト）
id	ID	一意に識別する数値
duration	時間（秒）	シーンやカットの長さ（null可）
time_of_day	時間帯	朝・昼・夕方・夜 など
se	効果音	BGM・環境音など
actors	登場人物	シーンに登場する人物（リスト）

🔸 sequences の記述例

✅ 正しい例：

sequences:
  - id: 1
    name: "第1シーン"
    scenes:
      - id: 1
        name: "冒頭の場面"

❌ 間違い例（インデント不正）：

sequences:
  - id: 1
  name: "第1シーン"  # ← 'name' のインデントがズレている

---

シーン・カット・セリフ関連

フィールド	日本語訳	説明
cuts	カットリスト	シーンを構成するショット群
camera	カメラ設定	カメラの種類、アングル、動きなど
action	動作	キャラクターや背景の動作説明
dialogue	セリフリスト	セリフのリスト（配列）
speaker	セリフの話者	各セリフの話し手
text	セリフ本文	話される内容（複数行も可）
transition	トランジション	カット間の映像切替（例: フェード）

🔸 dialogue の記述例（複数行セリフを含む）

✅ 正しい例（複数行セリフは | を使う）：

dialogue:
  - speaker: "吉"
    text: |
      あの……
      すみません、降ります。
  - speaker: "玉川"
    text: “あ、はい。すみません。（不満そうに）”
           

❌ 間違い例（1行にまとめる、改行が表現されない）：

dialogue:
  - speaker: "吉"
    text: "あの…… すみません、降ります。"  # ← セリフが改行されない

---

💡 注意事項

• インデントはスペース2つ or 4つで統一（タブはNG）
• テンプレートはスペースでインデントしているので、VSCodeではタブを押してもスペースに変換される
• リストは必ず - を使って明示
• 複数行文字列は | を使って記述
• YAML構文として通っても、SpDL構造として不正だとWebプレビューでエラーになる
• dialogue や actors など、期待される型（配列・マッピング）に注意

---

🔸 dialogue を空にする場合

✅ 正しい例（セリフがない場合でも構文を維持）：

dialogue: []

❌ 間違い例（文字列にしてしまう／不正な形式）：

dialogue: 
dialogue: "なし"  # ← NG（配列ではない）

---

📌大事なこと

sp.yamlでは「統一されたインデント」「正確なキーと値の記述」「可読性を意識した空行」が特に重要です。
必ず拡張機能コマンド（sp: シーン追加、sp: カット追加）を活用して、ミスや構文エラーを防ぎましょう。

---

✅ まとめ
改行は自由ですが、インデントだけは絶対に守ってください！

---

📄 SpDL 例

title: "風の谷の少年"
authors:
  - 伊丹シゲユキ
  - 山田太郎
  - 佐藤花子
created_at: "2025-05-31"
updated_at: "2025-05-31"
version: "1.0"
description: |
  風の谷に住む少年ユウが、不思議な風を追って旅立つ物語。
  少年の成長と出会いを描く短編シナリオ。
repository: https://github.com/yourname/yourproject

# これはコメントです。
# YAML形式で書かれたシナリオファイルの例です。
# 各要素はインデントで階層を表現しています。
# 各シーンは、ID、名前、説明、時間帯、SE（効果音）、登場人物、カットなどの情報を持っています。

sequences:
  - id: 1
    name: "旅立ち"
    description: "主人公が村を出て旅に出る"

    scenes:
      - id: 1
        name: "風の気配"
        duration: 90
        time_of_day: "早朝"
        se: "風のささやき"
        description: "朝の静かな村。風に導かれるようにユウが目を覚ます。"
        actors:
          - "ユウ"
          - "祖母"

        cuts:
          - id: 1
            camera: "窓辺で目を覚ますユウのアップ"
            description: "風に髪がなびく"
            se: "風の音"
            dialogue:
              - speaker: "ユウ"
                text: "……この風、どこから？"
                description: "目を細めながら"
            duration: 8
            transition: "カット"

          - id: 2
            camera: "祖母の部屋"
            description: "祖母が静かにユウを見る"
            se: ""
            dialogue:
              - speaker: "祖母"
                text: "風の声が聞こえたのかい？"
                description: "優しく"
              - speaker: "ユウ"
                text: "うん、呼ばれてる気がするんだ。"
                description: "真剣な表情"
            duration: 8
            transition: "ディゾルブ"

      - id: 2
        name: "出発"
        duration: 60
        time_of_day: "朝"
        se: "小鳥のさえずり"
        description: "ユウが村を出ていく"
        actors:
          - "ユウ"
          - "祖母"
          - "村人たち"

        cuts:
          - id: 1
            camera: "村の門前"
            description: "ユウが荷物を背負って立つ"
            se: "足音、鳥の声"
            dialogue:
              - speaker: "ユウ"
                text: "行ってくるね、ばあちゃん。"
              - speaker: "祖母"
                text: "風の導きに従いなさい。"
            duration: 7
            transition: "フェードアウト"

---

📜 ライセンス

MIT License

---

Created with ❤️ by buzzlyhan@gmail.com