jevreel

jevreel

Jevを使用した、埋め込みを一切使わない動画インテリジェンスのアプローチです。

jevreelは動画をラベル付きコンタクトシートに並べます。1秒につき1フレーム、画像1枚につき60フレームです。そして、TypeSafeの高速な判断モデルであるJevに、すべてのシートを並列で判定させます。最も有望な範囲は、フルフレームで再確認します。エージェント（Claude Code、Codex、Cursor、Claude Desktopなど、MCPに対応するものなら何でも）は、該当箇所、時刻、確率を受け取り、さらに詳しく調べます。ベクトルはどこにも計算・保存されません。

動作を見る

BlenderのオープンムービーTears of Steel（12:14、（CC）Blender Foundation、 CC BY 3.0）に対して、jevreel MCP サーバーとスキルを使った、編集なしのClaude Codeセッションを5つ紹介します。各クリップには記録内容がそのまま収録されています。エージェントのツール呼び出し、すべてのシートとフレームに対するJevの回答、該当箇所、コスト、そして引用されたエージェント自身の回答です。クリップをクリックすると、フル解像度の動画を見られます。

	質問	結果	Jev
1	誰かがジュースパックから飲む場面はありますか？	13枚のシートをスクリーニングし、6つの範囲をフルフレームで検証、2件を採用：2:28.5（p 0.95）と12:06.5（0.86）	19リクエスト、$0.0054
2	トムがセリアに謝るのはいつですか？何と言っていますか？	字幕を対象に音声モードで検索：6:47 "I'm sorry."（0.85）、5:02の思わず口にした "Sorry!" はエージェントが除外	10リクエスト、$0.0003
3	冒頭で誰かが新聞を読んでいます。見出しには何と書かれていますか？	最初の5分のみ検索：1:20.5（0.94）で検証。エージェントはフレームから ROBOTICIST CREATES KILLER ROBOTS と読み取った	8リクエスト、$0.0024
4	captain.jpgは登場人物です。彼が登場するシーンをすべて挙げてください。	写真で検索：8件の場面を見つけ、6件を0.86～0.97で検証、さらに2件をエージェントがzoomで確認	19リクエスト、$0.0064
5	映画の内容を整理してください：ロボット、銃、ホログラム、舞台、そして映画のジャンル。	エージェントが独自に4つの質問からなる観点を作成し、1分ごとの行を無料で読み返してから、映画全体について1つ質問	14リクエスト、$0.0051

1. 3秒間の場面を見つける

2. セリフを検索する

3. 画面に映っている文字を読む

4. 写真から人物を見つける

参照写真は 9:18 のフレームを切り抜いたものなので、9:17 のヒットはその写真の元となった映像です。ほかの 7 件が検索結果です。

5. 映画全体をマッピングする

セッションでは、失敗した 2 回の呼び出しもそのまま残しています。最初は録画で許可されていないシェルコマンド、次はフォルダーの指定ミスです。エラーには相対パスの基準となるフォルダーが示され、次の呼び出しは成功します。

埋め込みではなく判定モデルを選ぶ理由

マルチモーダル埋め込みモデルは、すでに動画を適切に検索できます。EmbeddingGemma 2（2026 年 10 月）はテキスト、画像、動画のフレーム、音声を 1 つのベクトル空間に配置し、スマートフォン上で動作します。jevreel は同じ目標に対して、異なるトレードオフを伴う別のアプローチを取ります。

• 固定された「類似性」の概念ではなく、質問に基づきます。 埋め込みインデックスでは、何を近いとみなすかをインデックス作成時に決めます。判定モデルは今の質問を評価し、コードでしきい値を設定したり、並べ替えたり、条件判定に使ったりできる確率を返します。
• 毎秒を低コストで処理します。 Jev で課金されるのは入力トークンのみで、出力は無料です。コンタクトシートを一度送信すれば、それに関するすべての質問を同じリクエストに含められるため、jevreel は少数のキーフレームではなく、動画全体を毎秒 1 フレームでスクリーニングします。
• 質問はほぼ無料なので、たくさん尋ねられます。 レンズを使うと、独自の型付き質問をほとんど追加コストなしで毎分に追加でき、その後は何度でも無料でフィルタリングできます。
• 高価なモデルには、条件を通過したものだけが渡ります。 エージェントが受け取るのは、サムネイルの山ではなく、重要な瞬間を捉えた少数のフル解像度フレームです。
• ランキングだけでなく、型付きの回答を返します。 毎分または動画全体について、該当する秒を添えたはい／いいえ、選択肢のいずれか、または設定した尺度上のレベルを返します。

大規模なライブラリを繰り返し検索する用途では、埋め込みのほうが適しています。ベクトルを一度作成すれば、各検索は無料の参照処理になります。一方、jevreel の質問ごとに、スクリーニングする分数に応じた Jev の料金がかかります（動画 1 時間あたり約 $0.02～0.03）。両者は相性よく組み合わせられます。埋め込みで動画を絞り込み、jevreel でその瞬間を見つけ、確認し、説明できます。

仕組み

flowchart LR
    V[video file or URL] --> F["ffmpeg: 1 frame/s"]
    F --> S["contact sheets<br/>60 labelled tiles, 1 minute each"]
    V --> T["captions, or local<br/>speech-to-text"]
    S --> J{{"screen: one Jev request<br/>per sheet, in parallel"}}
    T --> J
    J --> R["verify: top-ranked windows<br/>re-checked on full frames,<br/>every 0.5 s around the pick"]
    R --> H["hits: time, probability,<br/>frame, nearby speech"]
    H --> A["your agent: zoom, locate,<br/>read, cite 12:04"]

1. インデックス作成。 動画を毎秒 1 フレームでサンプリングし、フレームを 1568 px のコンタクトシートに並べます。各タイルには T01、T02 などのラベルを付けます。字幕を取得するか、ローカルで文字起こしします。各シートに、人物、画面上のテキスト、カット、設定、アクティビティ、代表的なフレームについて一度ずつ決まった質問をし、さらに追加したレンズについても質問します。これにより、型付きのタイムラインが作成されます。
2. スクリーニング。 シートごとに 1 回リクエストし、「この 1 分に含まれているか」についての yes/no（Noul）と、「何秒目か」についてのタイル ID から選ぶ Choice を尋ねます。スクリーニングと音声の質問は別々に行い、コード内で組み合わせます。
3. 検証。 上位にランク付けされたウィンドウ（しきい値ではなく順位で判定）を、選択した時点の前後 0.5 秒ごとに、全フレームについて yes/no で再確認します。スクリーニングでは、確認できない場合でも 1 秒間のイベントを正しくランク付けし、検証でそれを確認するか、誤った候補として除外します。
4. 詳しく見る。 zoom はフル解像度のフレームを再レンダリングします。locate は 1 つのフレーム内で対象を囲む Box を作成し、そこを切り抜きます。whole はストーリーボード、タイムライン、トランスクリプトをもとに、動画全体について 1 つの質問に答えます。

回答はキャッシュされます。同じ画像と質問を同じモデルに送っても、二度目以降に費用はかかりません。

これは TypeSafe 独自のパターンに沿っています。TypeSafe の行検索クックブックでは、ラベル付きの単位から選ぶ Choice と、「そもそもそこにあるか」を問う Noul を組み合わせています。画像ガイドでは、タイルから Choice で大きな画像を検索し、必要な箇所だけ詳しく確認します。Box ガイドでは、すべてのボックスを Noul で判定してから表示し、その境界を確認します。

クイックスタート

Python 3.11 以降、PATH 上の FFmpeg、および TypeSafe API キーが必要です。

uv tool install "jevreel[all]"
export TYPESAFE_API_KEY=...

jevreel index talk.mp4                       # prints the video id
jevreel ask talk "a slide with a bar chart"  # id, id prefix, path or title all work
jevreel zoom talk 12:00 12:10                # full-resolution frames to look at

[all] を指定すると、URL 対応（yt-dlp）とローカルでの音声テキスト変換（faster-whisper）が追加されます。これらがない場合、jevreel はローカルファイルをインデックス化し、動画と同じ場所に保存された .srt または .vtt の字幕を使用します。

レンズ：毎分に対する独自の質問

レンズとは、各シートに尋ね、タイムラインの列として保持する型付き質問のセットです。質問の種類は、noul（yes/no と、該当する秒数）、choice（選択肢から 1 つ選択）、または score（低いものから順に並べた段階）です。

# examples/lenses/driving.toml
name = "driving"

[[questions]]
name = "on_bridge"
type = "noul"
ask = "Is the car driving on a bridge?"

[[questions]]
name = "weather"
type = "choice"
ask = "What is the weather mostly like?"
options = ["clear", "cloudy", "rain", "snow", "fog"]

[[questions]]
name = "traffic"
type = "score"
ask = "How much other traffic is on the road?"
levels = ["None", "Light", "Moderate", "Heavy"]

jevreel index drive.mp4 --lens driving.toml     # rides in the indexing requests: almost free
jevreel lens drive driving.toml                 # or run it later: one request per minute of video
jevreel query drive "on_bridge > 0.7"           # filter as often as you like: no requests
jevreel query drive "weather == snow and traffic >= 2"

エージェントから使う

MCP サーバーは 10 個のツールを公開します。スキルはエージェントにワークフローを教えます。質問し、何かを断定する前に確認し、時刻を引用します。

プラグインとして使う

このプラグインには MCP サーバーとスキルがバンドルされています。uvx --from "jevreel[url]==0.2.0" でサーバーを起動するため、uv と PATH 上の FFmpeg が必要です。初回起動を速くするため、ローカルでの音声テキスト変換は含まれていません。利用する場合は、後述のように jevreel[all] を使ってサーバーを手動で追加してください。

Claude Code では、プラグインを有効にすると TypeSafe API キーの入力が求められ、システムの認証情報ストアに保存されます。

claude plugin marketplace add DeepAleph/jevreel
claude plugin install jevreel@jevreel

Codex はプラグインサーバーに許可リストに登録された環境変数だけを渡すため、キーを一度保存してください。同じコマンドでプラグインが起動する環境もインストールするため、初回起動は速くなります。

uvx --from "jevreel[url]==0.2.0" jevreel login
codex plugin marketplace add DeepAleph/jevreel
codex plugin add jevreel@jevreel

手動で設定する

Claude Code

claude mcp add jevreel -e TYPESAFE_API_KEY=your-key -- uvx --from "jevreel[all]" jevreel mcp

Codex

codex mcp add jevreel --env TYPESAFE_API_KEY=your-key -- uvx --from "jevreel[all]" jevreel mcp

Claude Desktop、Cursor、その他の mcpServers クライアント

{
  "mcpServers": {
    "jevreel": {
      "command": "uvx",
      "args": ["--from", "jevreel[all]", "jevreel", "mcp"],
      "env": { "TYPESAFE_API_KEY": "your-key" }
    }
  }
}

VS Code では、"type": "stdio" を指定して、同じエントリーを "servers" の下に設定します。

スキル（Claude Code、Codex、および Agent Skills を読み込むその他のエージェント）：

npx skills add DeepAleph/jevreel

MCP を使えないエージェントでも、CLI だけでスキルを利用できます。各コマンドは JSON を出力します。

ツール

MCP ツール	CLI	説明
index_video	jevreel index	シート、トランスクリプト、型付きタイムライン、および各レンズを生成します。MCP のバックグラウンドタスクとして実行されます。再度呼び出すとインデックスが返され、新しいレンズのみが実行されます。
ask_video	jevreel ask	説明に一致する場面を提示します。全フレームでスクリーニングと検証を行い、時刻、確率、前後の発話、フレームそのものを含みます。mode：visual、speech、both。
find_in_video	jevreel find	参照写真の被写体が映るすべての場面を検索します。
locate_in_frame	jevreel locate	フル解像度のフレーム1枚で対象を囲むボックスと切り抜きを取得します。
zoom_video	jevreel zoom	2つの時刻の間から、等間隔でフル解像度のフレームを取得します。
video_transcript	jevreel transcript	2つの時刻の間に話された内容を取得します。
ask_whole_video	jevreel whole	動画全体について、型付きの回答（はい／いいえ、選択肢、またはスコア）を1つ取得します。
run_lens	jevreel lens	インデックス済みの動画の各分について、独自の型付き質問を行います。
query_timeline	jevreel query	タイムラインを絞り込みます（デフォルトの回答とレンズ）。リクエストは発生しません。
list_videos	jevreel list	このマシンでインデックス済みの動画を一覧表示します。

jevreel measure <video> は、アカウントで複数のグリッドサイズのコンタクトシート1枚を生成するコストを報告します。

Python

import asyncio

from jevreel import Reel


async def main() -> None:
    async with Reel() as reel:
        video = await reel.index("talk.mp4")
        result = await reel.ask(video.id, "a slide with a bar chart")
        for hit in result.hits:
            print(hit.time, hit.probability, hit.frame)
        print(reel.query(video.id, "text_on_screen > 0.8").rows)


asyncio.run(main())

設定

変数	デフォルト	意味
TYPESAFE_API_KEY	（Jev に必須）	TypeSafe キーです。タイムラインなしのインデックス作成、ズーム、トランスクリプト、クエリはキーなしで利用できます。
JEVREEL_HOME	ユーザーのキャッシュフォルダー	インデックス済みの動画、シート、フレーム、回答キャッシュの保存先です。jevreel home で表示できます。
JEVREEL_MODEL	jev-1.14.0	意図的に固定しています。Box と画像タイルには 1.14 が必要で、エイリアスは変更されるためです。
JEVREEL_FPS	1	シートにサンプリングするフレーム数（1秒あたり。最大5）。
JEVREEL_TILES_PER_SHEET	60	シートあたりのフレーム数です。数を減らすとタイルが大きくなり、リクエスト数が増えます。
JEVREEL_VERIFY_TOP	6	各 ask で上位にランクされたウィンドウのうち、フルフレームで検証する数です。0 にすると検証を無効にします。
JEVREEL_CACHE	1	常に Jev に再度問い合わせるには 0 に設定します。
JEVREEL_CONCURRENCY	16	並列で行う Jev リクエスト数です。レート制限は TypeSafe アカウントごとに適用されます。
JEVREEL_ASR_MODEL	small	字幕がない動画に使用する faster-whisper モデルです。
JEVREEL_CAPTION_LANGUAGES	en,en-orig,en.*	URL から取得する字幕の言語を、優先順に指定します。

コスト

2026-10-15 に、入力トークン100万個あたり $0.042 の jev-1.14.0 を使用し、10分間の1080p動画で測定しました。

	リクエスト数	入力トークン数	コスト
コンタクトシート1枚（4×7～8×14のいずれのグリッドでも）	1	約6,000	$0.00025
インデックス作成（シート11枚、デフォルトの質問8件ずつ、実時間14秒）	11	78,000	$0.0033
5件の質問を含むレンズを後から実行	11	84,000	$0.0035
ask 1回（スクリーニングと検証を実施）	13–15	97,000–115,000	$0.004–0.005
同じ ask をもう一度実行	0	0	$0（キャッシュ）
locate（Box とエッジチェック）	2	5,000	$0.0002
whole（ストーリーボードのリクエスト1回）	1	7,600	$0.0003

動画1時間分に対する質問1件のコストは、約 $0.02～0.03 です。インデックス作成時に質問すると、レンズの質問はデフォルトの質問と一緒に処理されます。そのため「ほぼ無料」になります。質問8件のリクエストでも、質問2件の場合とほぼ同じコストです。TypeSafe はまだ画像トークン数を公開していません。これらの数値は API が報告したものです。jevreel measure でご確認ください。

実際の動画での測定結果

音声なしの10分間の1080pゲームプレイ映像をキャプチャし、すべての結果をフレームと手作業で照合しました。

クエリ	結果
"ゲームのポーズメニューが開いている"	3回の表示をすべて検出。それぞれ1秒未満：0:08.5、2:19.5、10:12.5（p 0.99～1.00）。スクリーニングのみでは、それぞれ0.36、0.50、0.95でした。検証前は3回中2回を見逃していました。
"全画面の街の地図が表示されている"	0:10と2:21で、どちらも地図画面でした。誤検出はありません。
"車が大きな鋼製トラス橋を渡っている"	2:07と5:05.5で、どちらも実際に橋を渡る場面でした。
レンズ driving：query "on_bridge > 0.7"	橋を渡る2分間を正確に検出（2:14と5:02）。
レンズ driving：query "menu_open > 0.7"	メニューが表示される3分間を正確に検出。
locate 「場所の名前のキャプション」5:02	枠で囲んで切り抜きました。切り抜き画像には「Fathers Bridge」と表示されています。
whole 「この動画は主に何を映していますか？」	「ビデオゲーム内のドライブシーン」、0.98。

制限事項

• 短いイベントでは、スクリーニングによる対象ウィンドウの順位付けが必要です。 検証では0.5秒ごとに確認しますが、対象は上位にランクされたウィンドウのみ（デフォルトでは6件）です。スクリーニングでそれより下位になったイベントは確認されません。JEVREEL_VERIFY_TOP を上げるか、より大きなタイルを使うには JEVREEL_TILES_PER_SHEET を下げてください。
• 音声は音声以外の情報を含みません。 Jev に渡される音声情報は文字起こしテキストのみです。
• Jev の画像サポートは実験段階です。 TypeSafe は images と Box を「dreamer-ready」としており、本番環境向けとはしていません。また、制限事項や精度はリリースごとに変わる可能性があるとしています。
• Jev が実際に受け付ける画像の最小サイズは各辺280ピクセルです。 ドキュメントには256とありますが、API は280未満の画像を拒否します（2026-10-15に測定）。jevreel は各画像に自動でパディングを追加します。
• しきい値は映像に合わせて調整が必要です。 報告用に0.5、「強い」判定用に0.7という値は、TypeSafe の例に従っています。テスト動画では有効でしたが、検証した動画は1本のみです。

コントリビューション

課題報告とプルリクエストを歓迎します。CONTRIBUTING.md を参照してください。コーディングエージェントは AGENTS.md を読む必要があります。

ライセンス

MIT。jevreel は独立したプロジェクトであり、TypeSafe AI とは提携していません。Jev は TypeSafe のモデルであり、TypeSafe の利用規約に基づき、公開 API を通じて使用しています。