docs: regenerate HTML/WASM docs with video vs clip comparison + timestamps

2026-05-19 12:51:10 +08:00
parent 5b2f9b35bf
commit c9bcdcb56a
28 changed files with 188 additions and 0 deletions
--- a/docs_v1.0/doc/01_auth.html
+++ b/docs_v1.0/doc/01_auth.html
@@ -389,6 +389,8 @@ curl<span class="w"> </span>-s<span class="w"> </span>-o<span class="w"> </span>
 <li><code>POST /api/v1/resource/tmdb/check</code> — test authentication + TMDb API connectivity</li>
 <li><code>GET /health/detailed</code> — view auth status (integrations section)</li>
 </ul>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/02_health.html
+++ b/docs_v1.0/doc/02_health.html
@@ -339,6 +339,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/03_register.html
+++ b/docs_v1.0/doc/03_register.html
@@ -446,6 +446,8 @@ curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">&quot;</s
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/04_lookup.html
+++ b/docs_v1.0/doc/04_lookup.html
@@ -292,6 +292,8 @@ curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/05_process.html
+++ b/docs_v1.0/doc/05_process.html
@@ -506,6 +506,8 @@ curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/06_search.html
+++ b/docs_v1.0/doc/06_search.html
@@ -281,6 +281,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/07_identity.html
+++ b/docs_v1.0/doc/07_identity.html
@@ -511,6 +511,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/08_identity_agent.html
+++ b/docs_v1.0/doc/08_identity_agent.html
@@ -98,6 +98,9 @@ a { color: #0066cc; }
 <span class="w">  </span>-H<span class="w"> </span><span class="s2">&quot;Content-Type: application/json&quot;</span><span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>-d<span class="w"> </span><span class="s1">&#39;{&quot;file_uuid&quot;: &quot;&#39;</span><span class="s2">&quot;</span><span class="nv">$FILE_UUID</span><span class="s2">&quot;</span><span class="s1">&#39;&quot;, &quot;trace_id&quot;: 10}&#39;</span>
 </code></pre></div>
+
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/08_media.html
+++ b/docs_v1.0/doc/08_media.html
@@ -273,6 +273,95 @@ curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">&quot;</s
 </tr>
 </tbody>
 </table>
+<h3>Video vs Clip: Quality &amp; Format Comparison</h3>
+<p>Both endpoints support time range extraction, but serve different use cases:</p>
+<table class="table">
+<thead>
+<tr>
+<th>Feature</th>
+<th><code>/video</code></th>
+<th><code>/clip</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>No params</strong></td>
+<td>Streams full file (Range seek)</td>
+<td>Returns 400 (params required)</td>
+</tr>
+<tr>
+<td><strong>HTTP Range</strong></td>
+<td>✅ Supported</td>
+<td>❌ Not supported</td>
+</tr>
+<tr>
+<td><strong>Encoding</strong></td>
+<td><code>-c copy</code> (zero encoding)</td>
+<td><code>-c:v libx264 -c:a aac</code> (re-encode)</td>
+</tr>
+<tr>
+<td><strong>Quality</strong></td>
+<td>Original (bit-exact, zero loss)</td>
+<td>Compressed (default CRF ≈ 23)</td>
+</tr>
+<tr>
+<td><strong>Format</strong></td>
+<td><code>video/mp4</code></td>
+<td><code>video/mp2t</code> (MPEG-TS)</td>
+</tr>
+<tr>
+<td><strong>Speed</strong></td>
+<td>Fast (no computation)</td>
+<td>Slower (encoding required)</td>
+</tr>
+<tr>
+<td><strong>Frame control</strong></td>
+<td>Time-based (<code>dur = (ef-sf)/fps</code>)</td>
+<td>Precise (<code>-vframes</code>)</td>
+</tr>
+<tr>
+<td><strong>Debug mode</strong></td>
+<td>❌</td>
+<td>✅ <code>mode=debug</code> overlay</td>
+</tr>
+<tr>
+<td><strong>Cache</strong></td>
+<td>❌</td>
+<td>✅ <code>max-age=86400</code></td>
+</tr>
+</tbody>
+</table>
+<h4>Usage Recommendation</h4>
+<table class="table">
+<thead>
+<tr>
+<th>Scenario</th>
+<th>Use</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Full video streaming / player seek</td>
+<td><code>/video</code></td>
+</tr>
+<tr>
+<td>Quick preview clip (zero quality loss)</td>
+<td><code>/video?start_frame=...&amp;end_frame=...</code></td>
+</tr>
+<tr>
+<td>Debug frame verification / text overlay</td>
+<td><code>/clip?mode=debug</code></td>
+</tr>
+<tr>
+<td>Precise frame count control</td>
+<td><code>/clip</code></td>
+</tr>
+<tr>
+<td>CDN cacheable clip</td>
+<td><code>/clip</code></td>
+</tr>
+</tbody>
+</table>
 <hr />
 <table class="table">
 <thead>
@@ -304,6 +393,8 @@ curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">&quot;</s
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/09_tmdb.html
+++ b/docs_v1.0/doc/09_tmdb.html
@@ -124,6 +124,9 @@ If local files exist, no external API call is made. Internet is only needed for
 <span class="w">  </span><span class="nt">&quot;api_latency_ms&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">120</span>
 <span class="p">}</span>
 </code></pre></div>
+
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/10_pipeline.html
+++ b/docs_v1.0/doc/10_pipeline.html
@@ -338,6 +338,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/12_agent.html
+++ b/docs_v1.0/doc/12_agent.html
@@ -208,6 +208,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc/13_config.html
+++ b/docs_v1.0/doc/13_config.html
@@ -138,6 +138,9 @@ curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>
 <span class="w">  </span>-H<span class="w"> </span><span class="s2">&quot;X-API-Key: </span><span class="nv">$KEY</span><span class="s2">&quot;</span><span class="w"> </span><span class="se">\</span>
 <span class="w">  </span>-d<span class="w"> </span><span class="s1">&#39;{&quot;enabled&quot;: true}&#39;</span>
 </code></pre></div>
+
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc_developer/11_error_codes.html
+++ b/docs_v1.0/doc_developer/11_error_codes.html
@@ -181,6 +181,8 @@ a { color: #0066cc; }
 </tr>
 </tbody>
 </table>
+<hr />
+<p><em>Updated: 2026-05-19 12:49:24</em></p>
 </div>
 </body>
 </html>
--- a/docs_v1.0/doc_wasm/modules/01_auth.md
+++ b/docs_v1.0/doc_wasm/modules/01_auth.md
@@ -278,3 +278,6 @@ Protected Request

 - `POST /api/v1/resource/tmdb/check` — test authentication + TMDb API connectivity
 - `GET /health/detailed` — view auth status (integrations section)
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/02_health.md
+++ b/docs_v1.0/doc_wasm/modules/02_health.md
@@ -185,3 +185,6 @@ curl -s "$API/health/consistency" -H "X-API-Key: $KEY" | jq '.checks[] | {check,
 | Method | Endpoint | Auth | Description |
 |--------|----------|------|-------------|
 | GET | `/api/v1/stats/sftpgo` | No | SFTPGo service status |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/03_register.md
+++ b/docs_v1.0/doc_wasm/modules/03_register.md
@@ -183,3 +183,6 @@ curl -s "$API/api/v1/files/scan?sort_by=status&page_size=5" -H "X-API-Key: $KEY"
 | **Sort order** | Default (`sort_by=name`): registered files first, then alphabetically. `sort_by=status`: alphabetical by status string. |
 | **Pagination** | `page_size` and `limit` are aliases. Default: show all results. |
 | **Processing order** | `pattern` regex filter → `sort_by`/`sort_order` → `page`/`page_size` slice. |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/04_lookup.md
+++ b/docs_v1.0/doc_wasm/modules/04_lookup.md
@@ -136,3 +136,6 @@ curl -s -X POST "$API/api/v1/unregister" \
 | `400` | Neither `file_uuid` nor `file_path`+`pattern` provided |
 | `404` | File UUID not found |
 | `401` | Missing or invalid API key |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/05_process.md
+++ b/docs_v1.0/doc_wasm/modules/05_process.md
@@ -234,3 +234,6 @@ curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | {
 | `count` | integer | Total job count |
 | `page` | integer | Current page number |
 | `page_size` | integer | Jobs per page |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/06_search.md
+++ b/docs_v1.0/doc_wasm/modules/06_search.md
@@ -143,3 +143,6 @@ Search text chunks spoken by a specific identity.
 | **Endpoint** | `POST /api/v1/embeddings` on port 11436 |
 | **Dimension** | 768 |
 | **Storage** | pgvector (`chunk.embedding` column) |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/07_identity.md
+++ b/docs_v1.0/doc_wasm/modules/07_identity.md
@@ -331,3 +331,6 @@ curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
 | `content-type` | `image/jpeg` or `image/png` |


+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/08_identity_agent.md
+++ b/docs_v1.0/doc_wasm/modules/08_identity_agent.md
@@ -63,3 +63,6 @@ curl -s -X POST "$API/api/v1/agents/identity/match-from-trace" \
  -H "Content-Type: application/json" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "trace_id": 10}'
 ```
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/08_media.md
+++ b/docs_v1.0/doc_wasm/modules/08_media.md
@@ -135,6 +135,32 @@ curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_time=30&en
 | **Codec** | H.264 + AAC |
 | **Cache** | `Cache-Control: public, max-age=86400` (24h) |

+### Video vs Clip: Quality & Format Comparison
+
+Both endpoints support time range extraction, but serve different use cases:
+
+| Feature | `/video` | `/clip` |
+|---------|----------|---------|
+| **No params** | Streams full file (Range seek) | Returns 400 (params required) |
+| **HTTP Range** | ✅ Supported | ❌ Not supported |
+| **Encoding** | `-c copy` (zero encoding) | `-c:v libx264 -c:a aac` (re-encode) |
+| **Quality** | Original (bit-exact, zero loss) | Compressed (default CRF ≈ 23) |
+| **Format** | `video/mp4` | `video/mp2t` (MPEG-TS) |
+| **Speed** | Fast (no computation) | Slower (encoding required) |
+| **Frame control** | Time-based (`dur = (ef-sf)/fps`) | Precise (`-vframes`) |
+| **Debug mode** | ❌ | ✅ `mode=debug` overlay |
+| **Cache** | ❌ | ✅ `max-age=86400` |
+
+#### Usage Recommendation
+
+| Scenario | Use |
+|----------|-----|
+| Full video streaming / player seek | `/video` |
+| Quick preview clip (zero quality loss) | `/video?start_frame=...&end_frame=...` |
+| Debug frame verification / text overlay | `/clip?mode=debug` |
+| Precise frame count control | `/clip` |
+| CDN cacheable clip | `/clip` |
+
 ---

 | Detail | Value |
@@ -144,3 +170,6 @@ curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_time=30&en
 | **Output** | Single JPEG via pipe (`image2pipe`, `mjpeg` codec) |
 | **Cache** | `Cache-Control: public, max-age=86400` (24h) |
 | **Frame number** | Zero-based (`frame=0` = first frame of video) |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/09_tmdb.md
+++ b/docs_v1.0/doc_wasm/modules/09_tmdb.md
@@ -107,3 +107,6 @@ curl -s -X POST "$API/api/v1/resource/tmdb/check" \
  "api_latency_ms": 120
 }
 ```
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/10_pipeline.md
+++ b/docs_v1.0/doc_wasm/modules/10_pipeline.md
@@ -120,3 +120,6 @@ The following routes are defined in source code but are **NOT** currently mounte
 | `/api/v1/search/persons` | `universal_search.rs` (not mounted) |
 | `/api/v1/who` | `who.rs` |
 | `/api/v1/who/candidates` | `who.rs` |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/11_error_codes.md
+++ b/docs_v1.0/doc_wasm/modules/11_error_codes.md
@@ -55,3 +55,6 @@ All API errors follow this JSON structure:
 | `E303_TMDB_CACHE_NOT_FOUND` | 200 | No local TMDb cache; run prefetch first |
 | `E304_TMDB_PROBE_FAILED` | 500 | TMDb probe execution failed |
 | `E305_TMDB_MOVIE_NOT_FOUND` | 404 | No matching TMDb movie found from filename |
+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/12_agent.md
+++ b/docs_v1.0/doc_wasm/modules/12_agent.md
@@ -116,3 +116,6 @@ Get status of the 5W1H agent pipeline for a file.
 | **Dimension** | 768 |
 | **Used by** | `parent_chunk_5w1h.py --embed`, story, 5W1H, search |

+
+---
+*Updated: 2026-05-19 12:49:24*
--- a/docs_v1.0/doc_wasm/modules/13_config.md
+++ b/docs_v1.0/doc_wasm/modules/13_config.md
@@ -85,3 +85,6 @@ curl -s -X POST "$API/api/v1/config/watcher-auto-register" \
  -H "X-API-Key: $KEY" \
  -d '{"enabled": true}'
 ```
+
+---
+*Updated: 2026-05-19 12:49:24*