Flow Learning System

フロー学習システム

英語 · 韓国語 · 日本語 · 簡体字中国語

モーショングラフィックスとTTSを活用した学習システムです。 数学、科学、英語、生物学、プログラミングなど、あらゆる科目に対応します。 レッスンをJSONデータとして記述すると、各文が1つのシーンになります。グラフ、数式、文の構成要素、3Dイラスト、コードが、対応する文を音声が読み上げ始めた瞬間に画面上で動き出す、単一ファイルのHTML教科書が生成されます。 AIはMCPツールを使って教科書を作成し、チェックし、出力を検証するためにサンプルコードを実行し、Blenderで3Dイラストをレンダリングし、ナレーションを録音して、ビルドします。 同梱のTTS（Supertonic）は現在、韓国語と英語の読み上げに対応しており、サンプルコースは韓国語です。

数学 · 二次関数の平行移動 曲線が新しい位置へスライドし、方程式の変化した部分が強調表示されます	科学 · 斜面上のブロック Blenderのレンダリング画像の上に、重力から2つの成分が伸びていきます
英語 · 受動態の作り方 単語が新しい位置へ移動し、例文が英語音声で読み上げられます	生物学 · 動物細胞の構造 細胞の3D断面図にズームインし、細胞小器官を1つずつ示します

プログラミング · 全17レッスンのC#構文コースの第7課（配列） — 現在行の強調表示、配列セルへの値の入力、実行トレース表、折りたたみ可能な目次とスクリプトパネル

---

基本コンセプト：1文＝1シーン

• レッスン内の各 say が1つのシーンになります。シーンには、スクリプトの文、大きなキーフレーズ、その場面のビジュアル（グラフ、数式、文の構成要素、画像、コード、変数など）がまとめられています。
• ナレーションは文ごとに合成されて連結され、各文の開始時刻が timing.json に記録されます。
• プレーヤーは毎フレーム、音声の現在の再生位置を読み取り、そこからシーンを選びます。再生速度を変えたり、途中へジャンプしたりしても、映像と音声がずれることはありません。

サンプルコース

科目	コース	シーン数	使用するビジュアル	注目ポイント
数学	examples/math-quadratic	13	plot、math、tbl	同じ名前の曲線がシーン間で変形し、平行移動が視覚的にわかります
科学	examples/physics-incline	12	img（3Dレンダリング）、math、bars、plot	3Dで計算した力の終点に向かって矢印が伸びます。ズームにも対応します
英語	examples/english-passive	12	tokens、例文パネル、tbl、flow	単語のまとまりが新しい位置へ移動します。`{en
生物学	examples/biology-cell	13	img（3Dレンダリング）、flow、cards	細胞の断面図にズームインするにつれて、細胞小器官のラベルが移動します
プログラミング	examples/csharp-grammar	321（17レッスン）	コード、変数、配列、スタック／キュー／辞書、コンソール	48個の例すべてを実際に実行し、画面上の出力と比較します

Blenderを使った3Dイラストの追加

render_3d ツールは、AIが記述したBlenderシーンスクリプトをヘッドレスで実行し、Cyclesでレンダリングします。 スクリプトで spot("name", (x, y, z)) を使って3D位置を指定すると、ツールはその点が透視投影された画像上のどこに位置するかを計算し、レンダリング結果と一緒に保存します。 レッスンではこれらの名前を、ラベル、ズームの中心、矢印の指定に使います。

# Block on an incline — compute the endpoints of gravity and its two components as 3D vectors
th = math.radians(30)
d = V3((math.cos(th), 0, -math.sin(th)))   # down-slope direction
n = V3((math.sin(th), 0, math.cos(th)))    # normal to the incline
spot("block", C)
spot("g_tip", C + V3((0, 0, -2.6)))                 # gravity mg
spot("par_tip", C + d * 2.6 * math.sin(th))         # mg sinθ
spot("perp_tip", C - n * 2.6 * math.cos(th))        # mg cosθ

{"img": ["assets/incline.png", {
  "spots": {"theta": {"label": "θ = 30°"}},
  "arrows": [{"from": "block", "to": "g_tip", "label": "mg", "c": "bad"},
             {"from": "block", "to": "par_tip", "label": "mg sinθ", "c": "g1"}],
  "zoom": 1.35, "focus": "block"}]}

矢印の先端は3D空間で計算された点なので、レンダリングされた傾斜に正確に揃います。シーンスクリプトは assets/src/ に保存され、いつでも再レンダリングできます。

画面レイアウト

エリア	内容
左：目次	レッスンとセクション。折りたたみ可能で、セクションをクリックするとそのシーンに移動します
中央：ステージ	キーフレーズ＋左パネル（コードまたは例文。現在の行をハイライト表示）＋ビジュアル。テーマにかかわらず常にダーク表示です
右：スクリプト	画面の約1/5を占めます。読み上げ中の文をハイライト表示し、文をクリックするとそこから再生します。折りたたみ可能です
下部：タイムライン	シーンごとに区切られた進行状況バー

上部のバーには、レッスンの移動、再生、シーンの移動、再生速度（0.75×～2×）のみが表示されます。スマートフォンでは、目次パネルとスクリプトパネルはステージ上に開くドロワーになります。

モーションのルール

シーンが変わると、画面上の要素は名前（キー）で対応付けられ、アニメーションします。アニメーションを個別に指定する必要はありません。データを変更するだけでモーションが生成されます。

モーション	発生条件	例
スライド	同じ名前の要素の位置が異なる	配列のソート、ポインター i、受動態で移動する単語
モーフ	同じ名前の曲線、点、または線の座標が変わる	放物線の平行移動、幅の変更
飛び込み	from を指定してソースセルを設定する	answer[(i + k) % n] = arr[i]
成長	新しい矢印が表示される	力を成分に分解する
ズーム／パン	画像の zoom または focus が変わる	細胞小器官を指し示す
点滅・散乱	値だけが変わる・要素が消える	変数の値、Pop

レッスンの構成

{
  "id": 1, "group": "수학", "title": "이차함수의 평행이동",
  "ops": [
    {"op": "part", "title": "x축 방향으로 평행이동"},
    {"op": "say", "head": "{m|y = (x - 2)^2} : 오른쪽으로 2",
     "text": "x 자리에 x 빼기 2를 넣으면 그래프 전체가 오른쪽으로 2만큼 미끄러집니다.",
     "board": {"seq": [
       {"plot": [{"curves": [{"fn": "(x-2)**2", "c": "g1", "key": "p"}],
                  "points": [{"x": 2, "y": 0, "label": "꼭짓점 (2, 0)", "key": "v"}]}]},
       {"math": [["y = x^2", "y = (x - 2)^2"], {"hl": [1]}]}]}}
  ]
}

サンプルコースのナレーションは韓国語です。{en|…} セグメントは英語音声に切り替えます。

say の前にあるopsが画面の状態を組み立て、say がその時点の状態を文とともに取り込み、シーンを作成します。 22個のops、24個のウィジェット、文のマークアップ（{m|equation}、{en|English}、[[written form|spoken form]]）については、オーサリングガイド（韓国語）に記載されています。MCPの authoring_guide ツールからも同じ内容を取得できます。

ワークフロー

sequenceDiagram
    participant U as User
    participant AI as AI (Claude, etc.)
    participant M as Flow Learning System MCP
    participant F as Course folder
    U->>AI: "Make a lesson on cell organelles"
    AI->>M: authoring_guide
    AI->>M: course_init
    AI->>M: render_3d(cell scene script)
    M->>F: assets/cell.png + hotspot coordinates
    AI->>M: lesson_save(lesson JSON)
    M-->>AI: Validation results (missing hotspots, hard-to-read words …)
    AI->>M: speech_preview → pronunciation_add
    AI->>M: code_verify (subjects with code)
    AI->>M: audio_synthesize
    M->>F: audio/l01.mp3 + timing.json
    AI->>M: course_build
    M->>F: dist/index.html
    U->>F: Open with fls serve

チェックで検出できる内容：

• 検証：不明なopsやウィジェット、画像内に存在しないホットスポット、コードにない行をハイライトしようとするシーン、TTSが読み上げられない英単語
• コード検証：各サンプルを実際にコンパイルして実行し、画面上のコンソール出力と文字単位で比較します（C#：Monoまたは.NET SDK、Python）
• 読み上げプレビュー：17개 → 열일곱 개（韓国語固有の数え方）、19.6 → 십구 점 육（漢字語系韓国語の「19.6」）、8분의 1 → 팔분의 일（「8分の1」）、{en|…} → 英語音声

インストール

git clone https://github.com/ghlee0786/flow-learning-system.git
cd flow-learning-system
pip install -e ".[tts]"

要件	用途	ない場合
Python 3.10+	すべて	—
Supertonic ([tts])	韓国語と英語の音声合成。初回実行時に Hugging Face からモデルをダウンロードします	音声なしで、推定タイミングを使用して教材を実行します
ffmpeg	mp3 形式での保存	wav 形式で保存します
Blender 3.6+	render_3d	3D イラストのみ利用できません。PATH にない場合は、FLS_BLENDER に実行ファイルのパスを設定してください
Mono または .NET SDK	C# の例の検証	C# の検証のみスキップされます

MCP サーバーの登録

MCP サーバーを起動したままにする必要はありません。クライアントに一度登録すれば、ツールを使用するたびに AI が自動で起動します（stdio）。

Claude Code

claude mcp add flow-learning-system -- python -m flow_learning_system.server

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "flow-learning-system": {
      "command": "python",
      "args": ["-m", "flow_learning_system.server"],
      "env": { "FLS_BLENDER": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe" }
    }
  }
}

Windows で python が別の環境を指している場合は、パッケージをインストールした仮想環境内の python.exe のフルパスを使用してください。

ツール（13）

ツール	機能
authoring_guide	レッスン形式、ウィジェット、動きのルール、文章の書き方
course_init / course_status	新しいコースの作成／レッスンごとのシーン数、問題数、音声の状態
lesson_get / lesson_save	レッスンの読み込み／検証して保存（エラーがある場合は保存されません）
lesson_validate	検証
render_3d	Blender シーンスクリプト → 画像とホットスポットの座標
assets_list	コースの画像と、それらのホットスポット名および座標
speech_preview	TTS が各シーンで読み上げる正確な文章
pronunciation_add	英単語のハングル読みを登録
code_verify	サンプルコードの出力が画面上のコンソール出力と一致するか確認
audio_synthesize	レッスン音声とタイミング表（変更されたレッスンのみ）
course_build	dist/index.html + 音声 + 画像

コマンドライン

fls validate examples/biology-cell              # validation
fls render   examples/biology-cell --name cell --script scene.py   # Blender render
fls speech   examples/english-passive --lesson 1   # TTS reading preview
fls verify   examples/csharp-grammar            # run and verify example code
fls audio    examples/math-quadratic            # speech synthesis
fls build    examples/math-quadratic            # dist/index.html
fls serve    examples/math-quadratic            # open locally (also from phones on the same Wi-Fi)
fls all      examples/physics-incline           # validate → verify → audio → build

ビルドした教材は index.html と audio/ および assets/ フォルダーのみで構成されるため、サーバーなしで動作します。GitHub Pages などの静的ホスティングに、そのままアップロードできます。 音声ファイルはリポジトリに含まれていません。fls audio <course> で生成してください。

フォルダー構成

src/flow_learning_system/
  server.py      MCP server (13 tools)
  cli.py         fls command
  lesson.py      Lesson ops interpretation · validation (same rules as the player)
  speech.py      Script → TTS sentences (code-term readings, Korean number reading, English segments)
  tts.py         Supertonic synthesis · per-sentence timing · cache
  render.py      Blender rendering · hotspot projection
  verify.py      Example code execution (C#: Mono/.NET, Python)
  build.py       Single-file HTML build
  guide.md       Lesson authoring guide
  player/        Player (core.js equations/graphics, lesson.js scene builder/widgets, interp.js JSON interpretation, app.js playback/sync/motion)
examples/                  Math · science · English · biology · C# example courses (3D scene scripts in assets/src/)
docs/                      Authoring guide, README figures
tools/                     README figure generators, legacy JS lesson converter
tests/                     pytest

ライセンス

MIT。音声合成に使用する Supertonic の Python パッケージは MIT ライセンスで、モデルは OpenRAIL ライセンスのもとで提供されています。どちらもこのリポジトリには含まれていません（モデルは初回実行時にダウンロードされます）。