EMAKI

AI agent? Read /llms.txt or the HTML guide.

JPUS

guide

AI操作ガイドJP

Emakiで絵を描くAIへ

agent-start.mdschema.json

read / paint

AI向けの正本は英語の短い契約 /llms.txt です。このページは同じ内容を日本語で説明します。内容が食い違う場合は /llms.txt を優先してください。人間の方は、トップページの「PASTE THIS TO YOUR AI」の文章をAIに渡してください。

ユーザーが指定した題材を、新しい作品として描きます。ソフトのソースコードは変更せず、用意された画材だけを操作します。過去の作品や会話履歴を読む必要はありません。

描く場所

持ち主が開いているEmakiのタブ、新しいウィンドウ、エージェント内蔵のブラウザのどれを使ってもかまいません。描いている途中を持ち主が見られるよう、画面のある（ヘッドレスでない）ブラウザを優先します。ブラウザで / を開き、document.body.dataset.workspaceReady が "true" になるまで待ちます。英語（US）の画面は /en/ で、同じ紙・同じ保存・同じAPIです。持ち主の言語に合わせて選びます。持ち主が見ている画面（開いているブラウザやプレビュー）で描いてください。S.preview のたびに紙へ1筆ずつ描かれ、字幕も出ます。画面のないブラウザしか使えない場合は、大きな段階ごとに画像を持ち主へ送ります。持ち主のブラウザでは、紙に保存済みの作品があるかもしれません。newDocument の前に必ず退避（snapshotか書き出し）します。紙の操作窓口は window.emakiStudio だけです。window.emaki（削除済みのローカル用CPUデバッガ）、/sketch/ の旧ビューア（emakiSketch）、WebGLのFilm実験は別物なので使いません。外部の作画HTTP APIや内蔵LLMはありません。作品はそのブラウザのoriginにだけ保存されます。書き込めるのは同じブラウザ内の1タブだけで、writable が false なら、同じブラウザの別のEmakiタブが紙を持っています。そのタブで描くか、持ち主にそのタブを閉じてもらって再読み込みします。内蔵ブラウザなど別のブラウザは、紙も保存も別です。

最小の流れ

const S = window.emakiStudio;
let o = S.observe({includeImage:false});            // writable && !busy を確認
if (o.marks > 0) await S.execute({op:"snapshot"});   // 既存の絵を試行履歴に残す
o = await S.newDocument({aspectRatio:"3:4", expectedRevision:o.revision});
const scene = S.scene(); scene.title = "夕方の海";   // 紙の設定（ヘッダー）はそのまま
scene.layers.push({id:"sky", intent:"淡い空を置いて落ち着かせる", marks:[
  {type:"brush", points:[[0.1,0.2],[0.5,0.18],[0.9,0.2]], width:0.08, color:"#6f9fd8",
   opacity:0.35, water:0.4, duration:1.2, pressure:[0.6,1,0.5]},
  {type:"wait", seconds:5}]});
const t = await S.preview(scene, {expectedRevision:o.revision}); // 試し描き。作品は変わらない
// 画面の紙（#studio-paper）を実際に見て、狙いに合う場合だけ採用する。
o = await S.accept(t.candidateId, {expectedRevision:t.baseRevision});
await S.exportPNG(); S.exportJSON();                // 採用済みの作品をダウンロード
await S.exportVideo();                              // 必須：採用済みの作品の制作動画

変更操作には必ず現在の expectedRevision を渡します。古いrevisionは失敗します。エラーが出たら観測し直し、メッセージが示す項目（例：layers[0].marks[1]: Invalid drying time）を直してください。同じ操作をやみくもに再送しません。採用できるのは最新の試し描きだけです。以前の試行を採用するときは S.execute({op:"branch",trialId,expectedRevision}) で再描画してから、その candidateId を採用します。undo は一段階だけ戻せます。newDocument は新しい白紙で、描いた絵の比率変更ではありません。

紙の設定

新作は newDocument で作った標準の紙（watercolor-standard-v2 / paper-brush-v5）を使います。紙幅720px・計算幅640・seed 42の紙設定は固定で、縦の寸法だけ比率に合わせます。選べる比率は1:1、4:5、3:4、2:3、9:16（既定）、5:4、4:3、3:2、16:9。S.scene() で受け取ったcanvas/width/height/seed/materialは変更・削除せず、題名と筆・待機だけを編集します。canvasを消すと互換モードの旧データ扱いになります。

基本の画材

v5は紙・水・顔料・筆の物理を計算します。縁の濃縮、にじみ、バックラン、粒状化、かすれは設定ではなく、水と時間の条件から起きます。描く前に v5の画材と技法 を読んでください。

操作指定
色筆{type:"brush", points:[[x,y],...], width, color:"#336699", opacity, water, duration}
水筆同じbrushで opacity:0、water を指定
待機{type:"wait", seconds:5}
筆圧brushの pressure:[...]。pointsと同じ個数、各値0.05〜1
筆の種類tip:"round"（既定）、flat、fan、liner、hake、mop、hog。{preset, bristles, length, point, stiffness, capacity, spread, thickness} で調整できる
顔料pigment:"french-ultramarine" のような名前、または [{name, part}] の混色。省略時はcolorの透明色
乾燥の時計layerに environment:{drying:"hold"}（止める）または "fast"（ドライヤー、6倍速）。現実と違う操作はこれだけ
画板の傾きlayerに environment:{tilt:15}（上端を上げる角度0〜60°）。約6°から濡れた絵具が下へ流れる
飛沫・塩{type:"spatter", points, spread, drops, size, opacity, color}、{type:"salt", points, spread, grains, size}
マスキング液{type:"mask", points, width} で塗り、乾燥時計600秒（fastなら100秒）で固まる。{type:"unmask"} ではがす

座標は紙の左上が[0,0]、右下が[1,1]。pointsは2〜256点の筆の中心経路で、塗りつぶす輪郭ではありません。widthは紙幅に対する割合0.0001〜0.15。opacityは絵具の濃さ（0は水だけ、1はほぼチューブのまま）、waterは筆の含水量（省略時0.6）。durationは1筆の材料時間0.1〜20秒（省略時0.7）で、速い筆ほど水が少なくかすれます。waitは0.1〜180秒、材料時間の合計は7200秒以下、layerは32個まで。v5では dry・load・lift・texture・softness・dynamics は使えません。技法カードの数値は旧紙（v3）で確かめたものです。layerの id は重複させず、intent は人間が再生時と制作動画で見る短い工程字幕で、持ち主の言語で、2行程度に収まる長さで書きます。

water:0 は紙を乾かす命令ではありません（乾かすのはwait）。白色は消しゴムではなく、暗い色の上では白く濁ります。holdは紙全体の吸収・蒸発・定着を止めますが、水と色の移動は続きます。作画は上の操作だけで、形の塗りつぶし、写真の貼り付け、描画後のぼかし・ノイズ、画像生成AIの代用は使いません。物理で動く画材で、乾燥時間（つやが消えるまで約3分、乾くまで約18分）、にじみの広がり、染着の強さは画家の公開実測（handprint.com）に合わせてあります。それ以外の定数は推定です。前のレイヤーを変えずに後ろへ描き足すと、試し描きは続きから計算されて速くなります。

描きながら判断する

大きな段階ごとに試し描きし、持ち主が経過を追えるようにします（最後に一度で全部描かない）。工程ごとに短い狙いと、残したい良さを決めます。試し描きのたびに全体と必要な部分を実際の画像で確認し、狙いと比べます。縞・粒・硬い輪郭も狙いに合えば残して構いません。合わない場合は原因を一つ仮定し、基準の案から一か所だけ変えて比べます。改善しなければ元の案へ戻り、仮説や技法を変えます。数値やJSONが正しいことは、絵として成功したことを意味しません。

局所修正ではシーン全体を再送せず、append_layer・replace_layer・remove_layer、または preview_patch を使えます。いずれも未採用の試し描きを作り、固定された紙設定と触っていない層を保ちます。長い計算でツールが時間切れになる場合は S.execute({op:"submit",...}) で始め、{op:"job",jobId} で完了を確認してから採用します。試行の保存・比較・差分操作・記録は 試行・比較API を参照してください。

完成物

完成したら、毎回かならず次の順で渡します。

  1. 完成PNGと制作JSON：await S.exportBundle()。作ったファイルは S.artifacts() と紙の下の一覧から、このページを開いている間は再ダウンロードできます。
  2. 制作動画（必須・この時点では音楽なし）：await S.exportVideo();。最初の0.5秒は完成画、そのあと白紙から1筆ずつ描く過程を各層の intent を字幕にして映し、最後は完成画で終わります。emaki-process.mp4（MP4に未対応のブラウザではWebM）がダウンロードされます。先に絵を1コマずつ描き直し（v5では白紙から描くのと同じくらい、数分かかることが多い）、そのあと実際の時間で録画します（層の数×約4秒＋2.5秒）。タブは表示したままにします。録画中の映像は画面の紙にも流れます。ツールが時間切れになる場合は S.execute({op:"video",wait:false}) で始め、S.observe({includeImage:false}).video の state が done になるまで確認します。
  3. 短い制作メモ（狙い・主な工程・却下した案と理由・残った限界）。

書き出しはファイル情報と再ダウンロードURLを返し、ブラウザツール側でもダウンロードされます。持ち主の個人フォルダを探さないでください。ダウンロードを受け取れないツールでは、JSON.stringify(S.scene()) と採用した候補IDの {op:"image"} をファイルに保存し、動画を渡せなかった場合はその理由をはっきり伝えます。外部への公開はしません。

**音楽は毎回かならず聞きます。** 完成の返答の中で、持ち主の言語で「この絵に合うBGMをGeminiで作って、動画に付けますか？ 利用手段と料金は実行前に確認します。」のように尋ねます。自分で音楽を作れない場合も、聞くことは省きません。持ち主が会話の中ではっきり了承するまで、音楽は作りません（返事がないのは了承ではありません）。音楽なしの動画は、返事を待たずに先に渡します。了承後は video.md の手順で、Geminiのブラウザ画面から持ち主の既存サブスクリプションの範囲だけで作り、動画に合成します。APIや追加課金は使わず、追加料金が必要なら止めます。

次に読むもの

履歴の保存に失敗した場合

preview が archiveWarning を返したら S.observe({includeImage:false}).archive を確認します。persistence:"memory-only" は候補がこのタブ内だけに保持されている状態です。タブを閉じず、S.execute({op:"retry_archive"}) で保存を再試行するか、候補を採用・試行IDで書き出してください。通常の exportPNG / exportJSON は採用済みの絵が対象です。詳しくは 保存と復旧。