> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/ja/rifarensu/sheet-format.md).

# シート形式仕様

このページでは、Squishツールが生成・消費するコンタクトシート形式を規定します。これが、シートを *アドレス指定可能な表現* にするものです。つまり、単なる画像ではなく動画の表現です。これに従う任意のツールは、モデルがナビゲートできるシートを生成し、シートに表示された任意のアドレスを再入力してズームできます。概念については [動画をアドレス空間として見る](/squish/ja/purimitibu/video-as-address-space.md) を参照してください。このページがその契約です。

## 対象範囲

準拠シートは単一のラスター画像です（参考実装では JPEG、品質 0.70 を出力します）。その中には次を含みます:

* 1つのソース動画（またはその時間ウィンドウ）からサンプリングしたフレームのグリッドで、時間順は厳密に昇順です。
* 各セルに、下記の文法に従ったタイムコードが刻印され、 **ソース動画のクロック基準で絶対的です**.

ここで規範なのは、グリッドの時間順、サンプリング規則、タイムコードの文法とその精度規則、絶対時刻の意味、ファイル名契約、およびラウンドトリップ性です。 *規範ではありません:* 視覚的なスタイル — 色、フォント、ピル形状、フッターブランディング、ピクセル寸法（参照 [安定性の対象外であるもの](/squish/ja/rifarensu/stability.md#what-is-not-covered)).

## グリッドのジオメトリ

密度は 4 種類あります。密度によって、1 回の実行で出力される各シートのセル数が固定されます:

| 密度    | グリッド  | シートあたりのセル数 | 参考エクスポート幅（参考情報） |
| ----- | ----- | ---------: | --------------: |
| `3x3` | 3 × 3 |          9 |         1536 px |
| `4x4` | 4 × 4 |         16 |         1920 px |
| `5x5` | 5 × 5 |         25 |         2304 px |
| `6x6` | 6 × 6 |         36 |         2560 px |

セルは時間順に並び、 **左→右、次に上→下**: セルインデックス *i* （0始まり）は列 *i* mod *cols*、行 ⌊*i* / *cols*⌋ を占め、サンプル時刻は *i*i

長い実行は、対象範囲の等しい連続スライスをカバーする複数のシートに展開されます。参考プロデューサーは、カバー範囲のおよそ 90 秒ごとに新しいシートを開き、1 回の実行あたり最大 4 シートに制限します。シート *N* は、後続のシートより厳密に早い時刻をカバーします *N*+1.

## サンプリング規則

フレーム時刻は決定的に選ばれます — **各セルは、シートのウィンドウにおける等分スライスの中央をサンプルします** :

対象範囲の長さを *L* とします（クリップ全体、または `end − start` の [zoom window](/squish/ja/rifarensu/cli.md#window-semantics)）、 *S* 個の等しいシートウィンドウ *W* = *L* / *S*に分割します。シートウィンドウの開始位置が *w₀*、セル i *i* の *N* サンプルする時刻は

```
t = w₀ + W · (i + 0.5) / N
```

調整は 2 つあります:

* **末尾マージン。** サンプルがクリップのちょうど末尾に到達することはありません（EOF へのシークでは何も返りません）。すべてのタイムスタンプは `duration − min(0.02 s, W/N/2)` にクランプされます — 小さなウィンドウでは半サンプルステップまで縮めた固定 20 ms のマージンで、末尾セルが同一タイムスタンプに潰れないようにします。
* **ウィンドウ指定の実行でも絶対値は維持されます。** ウィンドウ指定の実行は、長さ `end − start`の仮想的に切り詰めたクリップ上での実行として正確に計画され、その後 **すべてのタイムスタンプに +start が加算されます**。アドレスは常にソース動画のクロックを参照し、ウィンドウ指定の実行で再基準化されることはありません。

## タイムコード文法

### 出力形式

準拠プロデューサーは、各セルにサンプル時刻を次のいずれかの形式で刻印します:

| 形式         | 例                | 条件            |
| ---------- | ---------------- | ------------- |
| `m:ss`     | `1:30`, `120:30` | デフォルト（秒単位の精度） |
| `m:ss.d`   | `1:07.3`         | 小数 1 桁        |
| `m:ss.dd`  | `1:07.34`        | 小数 2 桁        |
| `m:ss.ddd` | `1:07.342`       | 小数 3 桁        |

規則:

* **分に上限はありません** — 1時間を超えるクリップでもスタンプされ `120:30`、決して `h:mm:ss`にはなりません。出力形式は値の大きさではなく構造で決まります。
* 秒は 2 桁にゼロ埋めされます（`0:07`, `1:07.3`).
* 値 **切り捨て** は表示精度で切り捨てられます — 次の秒や分に繰り上がることはなく、したがってスタンプがラベルより先のフレームを指すことはありません。

### 絶対性

すべてのタイムコードは **ソース動画のクロック**を参照します。ズーム（ `start`/`end` ウィンドウで再実行）すると、同じ *座標系* の中で、より細かいタイムコードが得られます — ウィンドウに再基準化されることはありません。これにより、エージェントはズームを連鎖できます。どの深さのシートから読み取ったアドレスでも次回呼び出しの境界として直接使用でき、引用は元の動画に対して有効なままです。

### 受け入れられる入力形式

準拠コンシューマー（ `--start`/`--end` フラグ、MCP `start`/`end` パラメータ）は次を受け入れます:

* **プレーンな秒数**: `90`, `67.4` （および MCP 上の生 JSON 数値）
* **`m:ss[.fraction]`** — 分は上限なし、秒は 1〜2 桁で 60 未満: `1:30`, `120:30`, `1:07.3`
* **`h:mm:ss[.fraction]`** — 分は 60 未満、秒は 60 未満: `01:02:03`

2 部構成か 3 部構成かは **コロンの数で決まり、値の大きさでは決まりません**。それ以外はすべて不正形式として拒否されます（CLI では使用法エラー、MCP ではツールエラーです）。

## 適応的精度

表示精度は、 **隣接するセルが常に異なるアドレスを表示する**ように調整されます。精度はサンプリングステップ（隣接セル間の時間間隔）から選択されます:

| サンプリングステップ | 精度     | 形式         |
| ---------- | ------ | ---------- |
| ≥ 1 s      | 秒単位    | `m:ss`     |
| ≥ 0.1 s    | 小数 1 桁 | `m:ss.d`   |
| ≥ 0.01 s   | 小数 2 桁 | `m:ss.dd`  |
| < 0.01 s   | 小数 3 桁 | `m:ss.ddd` |

1 つの規則がすべての出力面に適用されます。シートのピクセルに刻印されたラベルと `timecodes[][]` 配列が [MCP](/squish/ja/rifarensu/mcp.md#result-payload) / ホスト型 API の JSON

### アドレス指定可能な下限: 1 セルあたり 2 ms

エンジンはミリ秒精度でシークし、セルはウィンドウの中点でサンプルします。 **1 セルあたり 2 ms 未満のウィンドウでは**、隣接する中点が同じミリ秒に丸められる可能性があり、アドレスが黙って衝突してしまいます。したがって準拠プロデューサーは **拒否します** より小さいウィンドウを `セル数 × 2 ms` （例: 18 ms で `3x3`、72 ms で `6x6`）は、教育的なエラー（「ズームアウトするか密度を下げてください」）として返し、重複アドレスを生成しません。ちょうど下限に等しいウィンドウは受け入れられます。1 セルあたり 2 ms では、隣接する中点の差は少なくとも 2 ms になるため、丸めたシーク先と切り捨てられたラベルはそれぞれ少なくとも 1 ms ずつ異なります — 一意性は期待ではなく保証されます。

## ファイル名契約

シートの名前は

```
<basename>.sheet-N.jpg
```

で、 `<basename>` は、プロデューサーに渡された動画パスから派生したものです — 拡張子を除いたファイル名です — そして `N` は時間順における 1 始まりのシートインデックスです（`clip.mov` → `clip.sheet-1.jpg`, `clip.sheet-2.jpg`、…）。これは CLI と MCP サーバーが書き出すファイルの命名方法であり、形式は固定されています（参照 [安定性とバージョニング](/squish/ja/rifarensu/stability.md)).

1 つだけ文書化された例外があります。 [ホスト型 API](/squish/ja/rifarensu/http-api.md) はアップロードを独自の固定名で保存するため、応答 URL は常に `video.sheet-N.jpg` で終わり、アップロード時のファイル名には依存しません — 元の名前は応答の `input` フィールドに代わりにエコーされます。ホスト型のファイル名は `*.sheet-N.jpg` パターンで検証し、アップロード名では検証しないでください。

## ラウンドトリップ性

**`parseTime` はすべてを受け入れ `fmtTime` は出力します**: 上記のすべての出力形式は、あらゆる精度で受け入れ入力文法に含まれます。したがって、シートに表示されるものはすべて有効な `--start`/`--end` （CLI）または `start`/`end` （MCP）の入力です。エージェントは視覚でシート上のアドレスを読み取り、その正確な文字列を再入力してズームできます。この閉包性が [ナビゲーションループ](/squish/ja/purimitibu/the-navigation-loop.md) を変換レイヤーなしで動作させる要因です。

## 準拠

公開リポジトリのテストスイートは、この仕様の実行可能なゴールデン例として機能します — 参照 [`tests/`](https://github.com/getsquish/squish/tree/main/tests)、特に `window.test.ts` （ウィンドウ解像度、末尾クランプ、2 ms/セルの下限）と `report.test.ts` （出力契約の構造）。実装がこれらのテストと一致すれば、準拠しています。

## バージョニング

これは **v0** のシート形式です。進化は加法的であり、既存のジオメトリ、文法、意味論は v0 の範囲内では変更されません。新しい機能はそれらと並んで追加されます。シートメタデータを運ぶ JSON の面は、明示的な契約文字列でバージョン管理されます — 参照 [安定性とバージョニング](/squish/ja/rifarensu/stability.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/ja/rifarensu/sheet-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.