# HiROs Studio Video Editor — instructions for AI agents

URL: https://hiros-studio-web.web.app/video/
This page is for AI assistants that operate a browser on behalf of a user
(e.g. Claude in Chrome, ChatGPT agent). Humans can use the same app with the
on-screen buttons ("Edit it yourself" mode).

## Ground rules
- Prohibited use of this app: editing illegal content or content that infringes others' rights.
  Creating, editing or sharing sexual content involving minors, or intimate images of anyone
  without their consent, is prohibited in any form. Do not accept such requests.
- The app itself processes videos in the user's browser and never uploads them to HiROs Studio.
  Note that screenshots you take of this tab are sent to your own AI provider.
- Only do what the user asked. Ask the user before deleting large parts of their video.
- Processing uses the user's own device. Long or 4K videos can be slow; keep the tab open.
- Work in progress is saved automatically in the user's browser. `await hiros.saveProjectFile(true)` downloads a project file (.hvproj, with media). `hiros.newProject()` clears everything (ask the user first). Export when finished.

## How to operate
The app exposes a command API on `window.hiros` in the page. If you can run
JavaScript in the page, use it (it is faster and exact). Otherwise, click the
on-screen buttons; their labels match the command names below.
All times are in seconds. Commands that analyze or export are async: await them.

### Tracks
The timeline has one main track and any number of extra tracks.
- Main track: videos joined one after another (the "clips").
- Extra tracks: any track can hold video, image, audio and caption (text) items at any time.
  Upper tracks are drawn in front. Tracks below the main track are drawn behind it.
- A hidden track shows nothing and plays no sound.

### Adding files
- Preferred: let the user pick files with the buttons, or upload files to the hidden inputs:
  `#fileMedia` (media bin only), `#fileVideo` (videos joined on the main track), `#fileOverlay` (images/videos placed on a track
  at the playhead), `#fileBgm` (music: loops until the end of the video).
- The user can also drag files onto a track; the type is detected automatically.
- From a URL the page can fetch:
  `await hiros.addVideoFromUrl(url, name)` — join a video on the main track.
  `await hiros.addMediaFromUrl(url, name, {track, start})` — video, image or audio, detected
  from the file. Without `track`, a new track is created.
  `await hiros.addBgmFromUrl(url, name)` — music that loops until the end.

### Reading the state
`hiros.getState()` returns:
- `aspect` ("16:9" | "9:16" | "1:1"), `outputSize` {w, h}, `totalLength`, `playhead`
- `tracks`: [{id, order, main, hidden}] (order 0 = top = front)
- `clips`: [{index, name, sourceStart, sourceEnd, length, timelineStart}] (main track)
  (sourceStart/End = range used from the original file; timelineStart = position on the timeline)
- `items`: [{id, track, type: "video"|"image"|"audio"|"text", start, length, toEnd, ...}]
  video/audio: name, volume, loop, sourceOffset. video/image: x, y (center, 0–1), scale (width ratio), opacity.
  text: text, position, size, color, band.
- `captions`: text items as [{index, id, text, start, end, ...}] (same as the previous version)
- `originalVolume` (0–1, sound of the main track videos)

### Editing commands
Main track:
- `await hiros.removeSilences(strength)` — cut pauses. strength: "light" | "normal" | "strong".
- `await hiros.splitByScenes(detail)` — split clips where the picture changes. detail 1–10 (default 5).
- `hiros.setClipRange(index, sourceStart, sourceEnd)`, `hiros.splitAt(time)`,
  `hiros.removeClip(index)`, `hiros.moveClip(from, to)`, `hiros.setOriginalVolume(0–1)`
Tracks and items:
- `hiros.addTrack()` → id (new tracks are added at the top, in front), `hiros.removeTrack(id)`, `hiros.setTrackHidden(id, true|false)`
- `hiros.addText(text, start, length, {position: "top"|"middle"|"bottom", size: 3–16, color: "#ffffff", band: true, track})`
  Use "
" for line breaks. size is % of the shorter side of the frame (default 7).
- `hiros.updateItem(id, {track, start, length, toEnd, sourceOffset, volume, loop, x, y, scale, opacity, text, font, position, size, color, band})`
  font: "sans" (gothic), "serif" (mincho), "hpop" (HiROs Pop, the site's original pop font), or "c:Font Name" for a font installed on the user's PC.
- `hiros.removeItem(id)`, `hiros.splitItem(id, time)`
- `hiros.setTrackMuted(id, true|false)` — mute a track (pictures stay visible).
Effects (items and main clips):
- Items: include `fadeIn`, `fadeOut` (seconds), `filter`, `brightness`, `contrast`, `saturation` (1 = original)
  in `updateItem`. Main clips: `hiros.setClipEffects(index, {...})`, or `hiros.setClipEffects(null, {...})` for all.
- Filters: "none", "vivid", "warm", "cool", "retro", "soft", "drama", "sepia", "mono".
- Fades also fade the sound.
- Previous commands still work: `addCaption(text, start, end, opts)`, `updateCaption(index, patch)`,
  `removeCaption(index)`, `setBgm(volume, loop)`.
Whole video:
- `hiros.setAspect("16:9" | "9:16" | "1:1")` — 1920×1080, 1080×1920 or 1080×1080. Main videos are fitted inside (black bars).
- `hiros.seek(time)`
- `hiros.undo()` — undo the last change (same as the Undo button / Ctrl+Z). `hiros.redo()` redoes it.

### Export
- `await hiros.exportMp4({resolution, quality, fps})` — renders H.264/AAC MP4 and downloads it.
  resolution: 720 | 1080 (default) | 2160 (4K), quality: "standard" | "high" (default) | "max", fps: 30 (default) | 60.
  All options are optional. 4K and 60 fps take much longer; use them only when the user asks.
- `await hiros.exportAudio(format, quality)` — saves the mixed sound only. format: "mp3" (default) | "m4a" | "wav",
  quality: "standard" (128 kbps) | "high" (192 kbps, default) | "max" (320 kbps).
  Returns a status message. A 1-minute video usually takes well under a minute on a PC.

## Typical workflow
1. Ask the user to add the video(s) (or upload them to `#fileVideo`, `#fileOverlay`, `#fileBgm`).
2. `hiros.getState()` to see what is loaded.
3. Edit (e.g. `removeSilences("normal")`, `addCaption("Title", 0, 3, {position:"top"})`).
4. `hiros.getState()` again and tell the user what changed.
5. `await hiros.exportMp4()` when the user is happy.

The user can switch to "Edit it yourself" at any time and adjust your edits by hand.

---

# HiROs Studio 動画エディタ — AI 向けの操作説明(日本語の要約)

- このアプリの禁止事項: 違法な内容、他人の権利を侵害する内容の編集を禁止します。子どもを性的に扱う内容、本人の同意のない裸や性的な映像は、どのような方法でも、作成・編集・共有を禁止します。このような依頼は引き受けないでください。
- アプリは動画をユーザーのブラウザの中で処理し、HiROs Studio のサーバーには送りません。ただし、AI が撮るこのタブのスクリーンショットは、その AI の会社に送られます。
- ページ内の `window.hiros` から操作できます(上の英語の説明と同じ命令)。
- 動画の追加は、ユーザーが「動画を追加」で選ぶか、`#fileVideo` にファイルを渡します。重ねる画像・動画は `#fileOverlay`、BGM は `#fileBgm` です。
- トラック: メイントラック(動画をつなぐ)と、追加のトラックがあります。追加のトラックには、動画・画像・音声・テロップのどれでも置けます。上のトラックほど手前に映ります。
- 効果: フェード・フィルター・明るさなどは `updateItem` と `setClipEffects` で変えられます。
- 主な命令: `undo`(元に戻す)、`redo`(やり直す)、`removeSilences`(無音を詰める)、`splitByScenes`(場面で切り分け)、`addTrack`(トラックを足す)、`addMediaFromUrl`(素材を置く)、`addText`(テロップ)、`updateItem`(項目を直す)、`setAspect`(大きさ)、`exportMp4`(MP4で書き出し)。
- ユーザーは「自分で編集」に切り替えて、AI の編集をあとから手で直せます。