takeone

takeone

takeone はウェブアプリをヘッドレスで記録します。ライブブラウザーで動画をリハーサルすると、そのリハーサルがシナリオファイルになり、シナリオが独自のタイミングで再生されて記録されます。考えている時間は動画に表示されません。また、カーソル、ズーム、フレームは後から適用されるため、再録画せずにテイクのスタイルを変更できます。

ワークフローは次の順序で、5 つの段階に分かれています。

1. リハーサル。 アプリをライブでクリックして操作します。各ステップでページが表示されます。
2. 動画の開始位置をマークします。
3. エクスポート。 takeone が操作経路を再生して動作を確認し、シナリオを書き出します。
4. ドライラン。 記録時の速度で実行し、コンタクトシート（各ステップのフレームを並べた 1 枚の画像）を返します。
5. 記録。 動画をキャプチャしてレンダリングします。

インストールとセットアップ

最初の録画の前に、プロジェクトごとに一度だけ実行してください。各手順は安全に繰り返せます。

1. すでにインストールされているか確認します。 （プロジェクト内または videos/ フォルダー内の）package.json に takeone が記載されている場合は、手順 4 に進みます。

2. Node を確認します。 node -v が 20 以上である必要があります。Node がない、またはバージョンが古い場合は、ユーザーに伝えて中止してください。これがないと、ほかの作業は何もできません。

3. シナリオを置く場所にパッケージをインストールします。 エクスポートされたシナリオは import … from "takeone" を実行するため、シナリオと同じ場所にパッケージをインストールする必要があります。

   • JavaScript または TypeScript のプロジェクト（package.json がある場合）：ロックファイルで確認できる、プロジェクトで使用しているパッケージマネージャーを使って、takeone を開発依存関係として追加します。npm i -D takeone、pnpm add -D takeone、yarn add -D takeone、または bun add -d takeone を実行します。
   • それ以外の場合、またはアプリの依存関係に手を加えたくない場合： 動画専用のフォルダーを作成します。

     mkdir -p videos && cd videos && npm init -y && npm pkg set type=module && npm i -D takeone
     

     すべての takeone コマンドをこのフォルダーから実行します。シナリオファイル、.takeone/ 状態フォルダー、recordings/ はすべてこの中に保存されます。

   CLI はパッケージに含まれています。npx takeone <command> で実行します。npx takeone guide を実行すると、ワークフロー全体が 1 画面に表示されます。グローバルインストール（npm i -g takeone）では takeone コマンドを直接使えますが、シナリオには引き続きローカルインストールが必要です。

4. マシンを準備します。 npx takeone setup を実行します。次の処理が行われます。

   • Chromium をダウンロードします（約 650 MB。マシンごとに 1 回）。
   • パッケージに同梱されている ffmpeg を確認します。
   • ヘッドレスブラウザーを起動し、記録できることを確認します。

   最後に Ready. と表示されるか、問題の内容を示す ✗ の行が表示されます。Linux サーバーでは、システムライブラリの不足がよくある原因です。npx takeone setup --with-deps で修正できます。このコマンドには sudo が必要です。sudo を使えない場合は、ユーザーにこのコマンドを実行してもらってください。

5. MCP サーバーを登録します（任意ですが推奨）。 MCP サーバーの応答にはスクリーンショットが含まれるため、1 回の呼び出しで操作とページの表示の両方ができます。使用中のエージェントに登録します。

   claude mcp add takeone -- npx -y takeone mcp     # Claude Code
   codex mcp add takeone -- npx -y takeone mcp      # Codex
   

   ほかのクライアントでは、MCP 設定に {"command": "npx", "args": ["-y", "takeone", "mcp"]} を指定します。

   MCP サーバーはセッション開始時に読み込まれるため、ツールが表示されるのは次のセッションからです。表示されるまで待たず、残りの作業には CLI を使い、再起動すれば MCP ツールを使えることをユーザーに伝えてください。MCP サーバーと CLI は同じブラウザーセッションを共有するため、両者を切り替えても状態は失われません。

後で更新するには、npm i -D takeone@latest を実行してから npx takeone session stop を実行し、実行中のブラウザーセッションに新しいバージョンを読み込ませます。

コマンド

手順	MCP ツール	CLI
開始、必要に応じてログイン	takeone_start {scenario, url, headed, viewport}	--scenario login.ts を指定した最初のコマンド
操作	takeone_do {verb, target, text}	npx takeone do <verb> <target> [text]
ページを見る	takeone_look {filter, role, all}	npx takeone look
マーク	takeone_mark {name: "start"}	npx takeone mark start
ジャーナル	takeone_journal {action, ids}	npx takeone journal [drop|keep|setup] 3-5
エクスポート	takeone_export {file}	npx takeone session export demo.ts
ドライラン	takeone_dry_run {file}	npx takeone dry-run demo.ts
録画	takeone_record {file}	npx takeone record demo.ts
ブラウザーを停止	takeone_stop	npx takeone session stop

動詞：goto、click、type、press、hover、scroll、scroll-to、wait-for、wait-url、wait、zoom、zoom-out。

ブラウザーを開く前に動画を計画する

最初の goto の前に、ストーリーを3～6つの場面に分けて書き出します。たとえば、「Projectsを開き、プロジェクトを作成して、一覧に表示し、ステータスをズームして見せる」とします。それぞれの場面で、視聴者が変化を確認できるようにします。その後、その場面だけをリハーサルします。動画に含めるクリックと、単に画面を見回すためのクリックが分かるので、計画を立てるとリハーサルが短くなります。

• 表示が整ったページから始めます。 録画はスピナーではなく、すでに読み込み済みのページから始めます。ナビゲーションや準備は mark start より前に行うか、視聴者に見せない操作は mark setup の後に行います。
• 録画前にデータを準備します。 動画に既存のアイテムが必要な場合は、セットアップ手順またはアプリのAPIを使って、リハーサル前に作成します。カメラの前で作成するのは、作成すること自体が動画の主題である場合に限ります。
• 短くまとめます。 動画1本あたり20～60秒を目安にします。長い動画を1本作るより、短い動画を2本作るほうが、うまく仕上げやすく、視聴もしやすくなります。

リハーサル：画面を読み取り、番号で操作する

最初の goto でChromeが起動します。新しいページに移動する操作やダイアログを開く操作を行うと、その都度 view が返されます。viewには画面上のすべての要素が番号付きで領域ごとに表示され、マークアップ上で各要素がどのような働きをすると示されているかが記載されます。

header
  1 link "Acme" [icon logo] → /
sidebar "Workspace"
  4 link "Projects" [current] → /projects
main
  12 button "New project"
  13 button [icon ellipsis] (opens menu)
  14 switch "Email alerts" [off]
off screen: 22 more elements. Headings: 30 "Members", 41 "Billing"

viewにはスクリーンショットも付属し、同じ番号が描かれています。MCPでは画像が添付され、CLIではそのパスが出力されます。まずテキストを読みます。テキストだけでは分からない場合、たとえばレイアウト、アイコン、グラフ、またはカメラに映したときの見た目を確認する場合に、スクリーンショットを開きます。その後、番号を指定して操作します：click 12、type 5 "acme-prod"、zoom 14。番号は直近のviewを参照します。

それ以外の操作では、変更された内容だけが出力されます。

• + 新しい要素とその番号
• - 削除された要素
• ~ 状態の変化
• アラート、ダイアログ、ページエラー（!）

次の操作を決めるには通常、この差分だけで十分なので、操作のたびに look を呼び出す必要はありません。

ターゲットには、通常の語句（"new project"）、role:name（button:Create）、text=Deployed、css=.monaco-editor、または座標 640,360 も指定できます。名前が数字のコントロールには、button:2 を使用します。

viewの各行は、マークアップから読み取られます。takeoneは、要素の動作を確認するためにクリックすることはありません。これは意図的な仕様です。DeleteやCreateボタンをバックグラウンドで試せば、実際に処理が実行されてしまうためです。

コマンドの使い分け

状況	使用するもの	使用しないもの
ページに移動したとき、またはダイアログを開いたとき	do がすでに出力したビュー	追加の look
クリック、入力、キー押下の後	変更レポート（+、-、~）	look。ただし、ページが変化し続けているとレポートに表示された場合を除きます
アイコン、レイアウト、グラフ、カメラに映したときの見た目など、テキストでは確認できないもの	スクリーンショット（MCP 経由ではインライン表示、CLI では view: パス）	名前からの推測
画面外にあるものや、長いページで何かを探すとき	look --filter <text>、続けて scroll-to <n>	むやみにスクロールして、もう一度確認すること
最新のビューにあるものを操作するとき	その番号（click 12）	名前を入力し直すこと
読んでいるビューからページが変わったとき、またはラベルが分かっているとき	通常の単語（click "new project"）	古いビューの番号
同じ名前のコントロールが複数あるとき	その番号、または --nth を付けた role:name。エクスポートでは可能な場合、隣にあるテキストで対象を指定します	CSS セレクター
保存、デプロイ、プロビジョニングなど、アプリの処理を待つとき	十分な長さの --timeout を付けた wait-for "<text that appears>"	推測に頼る wait <ms>
ビューアーが読む時間を少し取るとき	wait 800 から wait 1500	何もしないこと。手順を立て続けに行うと慌ただしく感じられます
結果を拡大して見せるとき	zoom <n>、続けて zoom-out	クリックのたびにズームすること。クリック後は自動でズームされます
エクスポート前に操作経路を確認するとき	journal	エクスポートしてからうまくいくことを期待すること
録画前に動画全体を確認するとき	dry-run、続けてコンタクトシートを確認	まず record を実行すること。録画に失敗すると数分が無駄になります
シナリオの編集中に操作経路を手早く確認するとき	dry-run --fast	高速パスを、録画も問題なく完了する証拠と見なすこと
見た目（背景、カーソル、サイズ）だけを変更するとき	別の設定を指定した render <recording-dir>	再度録画すること
完了したとき、または takeone を更新した後	session stop	ブラウザーを起動したままにすること

explore と find は、URL によってページの一覧を取得するための古いコマンドです。ビューと look --filter を使えば、同じ範囲をより少ない手間で確認できます。

うまくリハーサルする

• 動画と同じ操作経路を、順番どおりにリハーサルします。 余分な寄り道は自動的に除外されますが、手順を追加するたびにジャーナルで確認する項目も増えます。
• 動画の開始位置にページが移動したら、すぐに mark start を呼び出します。 その前の内容はすべて動画から除外されるため、最初にページを見て回っても問題ありません。
• ビューアーに読ませたい内容を入力します。 現実的な名前や値（「test123」ではなく「acme-prod」など）を使います。入力した内容は画面に表示されます。
• 手順に失敗したら、再試行する前にエラーを読みます。 エラーにはページに表示された内容が示されます。ログインページが表示された場合、セッションは認証されていません。「not found」の場合は、URL または ID が間違っています。同じ手順を再試行しても、解決することはほとんどありません。
• 操作経路が変わったら再リハーサルし、タイミングだけが変わった場合はファイルを編集します。 待ち時間、入力速度、ズーム倍率、追加の間などは、エクスポートしたシナリオの 1 行を編集すれば変更できます。クリック順が変わる場合は、新たなリハーサルとエクスポートが必要です。
• 完了と判断する前に確認します。 dry-run のコンタクトシートと、record が出力するキーフレームシートを確認します。すべての場面が正しく表示されているか、何かが見切れていないか、カメラに読み込み中の状態が映っていないかを確認してください。

リハーサルから動画へ

1. 動画を開始する前は自由に操作してください。 ページを以前の状態に戻す手順は、寄り道としてエクスポートから除外されます。たとえば、メニューを開いてから閉じる操作が該当します。
2. 動画を開始する場所で mark start を呼び出してください。 それ以前の操作はすべて、画面を見て回るためのものとして扱われます。撮影に含めない準備が必要な場合は、mark start の前に mark setup を呼び出してください。例：プロジェクトを開く、フォームをクリアする。
3. エクスポートする前にジャーナルを確認してください。 journal ツールを使うと、各手順でページがどの状態になったか確認できます。誤って除外された手順を復元するには keep を、手順を削除するには drop を使います。
4. エクスポートします。 まず新しいタブで、残した手順を再生します。再生に失敗すると、エラーには該当する手順の名前と、ページに表示された内容が示されます。
   • エクスポートされたファイルでは、ビュー番号ではなく、ロールと名前で要素を指定します。
   • 現在の件数やバッジを含む名前は、パターンとして記述されます。たとえば、"Issues 157" は /^Issues(?![\w.])/ になります。
   • 既存のファイルにエクスポートすると、// takeone:steps-begin と // takeone:steps-end の間のブロックだけが置き換えられるため、その外側の編集内容は保持されます。
5. 録画する前にドライランを実行してください。 録画時とまったく同じペースでページを再生するため、ドライランが成功すれば録画も成功します。コンタクトシートを確認してください。動画全体を確認する最も手軽な方法です。
6. 録画します。 結果は recordings/<name>-<time>/output.mp4 と、撮影内容を確認するためのキーフレームシートです。

エクスポートされたファイルは通常の TypeScript です。再度リハーサルするより手早い場合は、タイミング（s.wait）、入力速度、ズームを手動で編集してください。references/scenario-api.md にすべてのメソッドとオプションが記載されています。

ログインが必要なアプリ

ログイン処理をシナリオの explore.setup に記述し、そのファイルを使ってセッションを開始してください。セッションでは一度ログインし、その後のすべての手順で同じログイン状態を再利用します。エクスポートされたシナリオは、そのファイルをインポートし、録画前に同じログイン処理を実行します。

import { defineScenario, withExplore } from "takeone";

export default withExplore(defineScenario({ name: "login" }, async () => {}), {
  pages: [],
  setup: async (page) => {
    await page.goto("http://localhost:3000/login");
    await page.fill('input[name="email"]', process.env.DEMO_EMAIL!);
    await page.fill('input[name="password"]', process.env.DEMO_PASSWORD!);
    await page.click('button[type="submit"]');
    await page.waitForURL(/dashboard/);
    // App state the video needs: a theme stored by the app itself, hidden banners, and so on.
    await page.evaluate(() => localStorage.setItem("theme", "dark"));
  },
});

認証情報は環境変数から読み込んでください。ファイルに直接記述しないでください。

browser.colorScheme: "dark" は、ページが prefers-color-scheme を通じて参照するブラウザーのダークモード設定を指定するだけです。アプリが独自のテーマ設定を保持する場合は、上記のようにセットアップで設定してください。

見栄えをよくする

• クリックのたびではなく、見る人のためにズームしてください。 自動ズームはクリックや入力をすでに追従しており、zoom.auto で制御できます。結果、ステータス、変更された値など、見る人が読み取る必要がある箇所には明示的な zoom を追加してください。約 1.5 秒表示したら、カーソルが大きく移動する前に zoom-out してください。1 分あたり 2〜4 回、意図的にズームするほうが、動き続ける映像より見やすくなります。あるセクションで自動ズームを無効にするには、s.autoZoom(false) を呼び出してください。
• 時間のかかる手順は実際の時間に沿って見せてください。 デフォルトでは、待機時間は実時間で再生されます。s.lapse(8, () => …) を使うと、長い待機をタイムラプスで表示できます。s.trim(() => …) を使うと、待機を短縮できます。
• 鮮明に撮影してください。 デフォルトでは、ビューポートは 1920x1080、deviceScaleFactor: 2 です。これにより、ズームしても鮮明さが保たれます。出力サイズは別に設定します（output.width、output.height、output.fps）。4K で出力する場合は、deviceScaleFactor: 3 で撮影してください。録画し直さずに既存の撮影内容のスタイルを変更するには、別の frame、cursor、または output 設定とともに takeone render <recording-dir> を実行してください。
• 短い撮影を優先してください。 長いシナリオを 1 つ作るより、短いシナリオを複数作るほうが仕上げやすくなります。record --no-render の後に render を実行すると、撮影とスタイル調整を分けられます。

知らないと時間がかかること

• リハーサルやドライランでは実際のデータが変更されます。 ユーザー、プロジェクト、ファイルを作成すると、実際に作成されます。後の実行で「名前はすでに使用されています」というエラーが発生しないよう、固有の名前を使うか、実行の合間にアプリをリセットしてください。
• 一部のテキストフィールドはページ一覧に表示されません。 コードエディター（Monaco）とターミナル（xterm）は、非表示のテキストボックスから入力を受け取ります。エディターをクリックしてから、対象を指定せずに入力してください（テキストだけを指定した type）。これにより、フォーカスがある要素に入力されます。
• 記録中のキー操作は素早く実行されます。 リハーサルでは、別々の press 呼び出しの間にショートカットのタイミングを逃すことがあります。たとえば、g の後に i を入力する場合です。エクスポートされたシナリオでは連続して実行されるため、アプリが壊れていると判断する前にドライランで確認してください。
• ページの問題は ! で始まる行に表示されます。 401 やクラッシュは、ステップの出力に ! HTTP 401 … のように表示されます。エラーに「ログインページ」や「見つかりません」とある場合、要素名ではなく、URL または認証に問題があります。
• 処理が止まることはありません。 すべてのコマンドは、いつまでも待機せずエラーを返して終了するため、コマンドを長いタイムアウトで囲まないでください。名前付きターゲットは、要素が表示されるまで browser.timeout（15 秒）待機します。
• 1 台のマシンで 2 つのエージェントを使う場合は、別々のセッションが必要です。 2 つ目のエージェントでは TAKEONE_SESSION_PORT=9322 を設定してください。専用のブラウザーが割り当てられます。
• 更新した takeone は、実行中のセッションには反映されません。 更新前に開始したセッションでは、古いコードが実行され続けます。CLI が警告を表示します。セッションを再起動するには、takeone session stop を実行してください。

SDK

シナリオは TypeScript モジュールであり、ランナーはコードから使用できます。

import { recordScenario, renderRecording, dryRunScenario } from "takeone";
import scenario from "./demo.js";

const rec = await recordScenario(scenario, { outDir: "out/demo" });
await renderRecording({ recordingDir: rec.outDir, config: { frame: { background: "#0b0b0f" } } });

セッションメソッド、ターゲット、すべての設定オプションについては、references/scenario-api.md を参照してください。