docs/studio_walkthrough.md

# Meridian Studio — walkthrough film

[← Research article](research.md#try-meridian) · [Studio guide](studio.md)

**Status: a 38-second preview-only overview is available; a matching generated take is still pending.**
[Watch the concise Studio overview](../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_concise.mp4)
· [Editing recipe](../videos-all/studio_walkthrough/nba3_preview_live_02/edit_concise_01/edit.json).

The concise edit uses restrained English titles and enlarged details of the actual UI:
**one source → camera position and aim → held source time → geometric reference**.
It omits repetitive authoring and backend waits, disclosed on screen, without accelerating the
remaining actions. The complete supplied input and 243-frame geometric reference are retained;
the UI capture is resampled from 25 to 24 fps. It is silent, with no final generated video implied.
The original recording remains unchanged:

[Watch the revised, uncut recording](../videos-all/studio_walkthrough/nba3_preview_live_02/studio_walkthrough_review.mp4)
· [10-second geometric reference](../videos-all/studio_walkthrough/nba3_preview_live_02/preview_truth.mp4)
· [Before / after camera comparison](../videos-all/studio_walkthrough/nba3_preview_live_02/review_camera_comparison.jpg)
· [Session evidence](../videos-all/studio_walkthrough/nba3_preview_live_02/session.json).

NBA3 replaces the flower scene as the current walkthrough candidate: approach → airborne hold with
camera travel → resumed dunk and landing. The
[earlier flower pilot](../videos-all/studio_walkthrough/flowers_preview_live_01/studio_walkthrough_review.mp4)
is retained, not overwritten.

**Revision 02 replaces the large orbit/approach with small athlete-framed lateral travel.**
The athlete and hoop are substantially more legible in the held reference, and the source map
continues through the dunk and landing. Review included contact sheets covering all 243 reference
frames and larger comparisons at output frames 60, 134 and 179. The backend's average coverage
rose from 61.2% to 83.9%; that is a geometric diagnostic, not a generated-quality score.

**The reference still has conspicuous disocclusion holes and tearing around the athlete's outline.**
This is a more useful authoring demonstration, not an approved cinematic result. Native-speed motion
review and a matching generated take are still needed before publishing the research-page film.
The [rejected first camera pilot](../videos-all/studio_walkthrough/nba3_preview_live_01/studio_walkthrough_review.mp4)
is retained for comparison, not silently replaced.

The September 13 recordings ran through Chromium against the existing Studio at `127.0.0.1:8412` on GPU 0,
with permission to execute outside the restricted sandbox. It records actual seven-key authoring and
geometric previews; **no final generation was submitted**. The running main-repository Studio has
the same authoring controls as the release, with minor comment/warning-text differences; the served
HTML is retained. Revision 02 completed 81 POST requests with no recorded API/browser errors and
no `/render` request. The preview workflow passed its live checks; the script's `--render` branch remains
untested. This is raw workflow evidence, not yet an approved research-page film.

The older files named `browser_studio.png` are screenshots of a separate source/control gallery,
not this camera-authoring application. Do not substitute them for a Studio demonstration.

## Record with Playwright

[Recording script](record_studio_walkthrough.py) — run it in a terminal where Chromium can launch
and `http://127.0.0.1:8412` is reachable. That address means **the machine running the script**;
use an existing private tunnel or `--url` if the Studio runs elsewhere. Do not expose the unauthenticated
service publicly. The script connects to an existing service; it does not launch, restart or cancel it.

**Arrange a free service/GPU slot first.** Even without `--render`, uploading triggers reconstruction,
and editing triggers point-cloud, thumbnail and full-path warp work. The script waits between edits;
it is not a CPU-only recording tool and cannot determine whether other users need that GPU.

From the release root, make a preview-only pilot:

```bash
PY=/home/chenyun/miniforge3/envs/wan_new/bin/python
"$PY" docs/record_studio_walkthrough.py \
  --source videos-all/nba3_teacher30/nba3_full_event.mp4 \
  --camera-style nba-glide \
  --url http://127.0.0.1:8412 \
  --out videos-all/studio_walkthrough/nba3_preview_02
```

This NBA3 plate contains the complete event in **124 frames at 24 fps**, already prepared from the
supplied clip. The hold uses frame 60, during the airborne ball sweep before the dunk; the action
then resumes through the landing. For another scene, choose a clean clip with at least 124 normalized frames
before its first detected cut. It stops if that prepared span is shorter; it does not silently adapt
the timing sketch. Retain source permission/attribution when substituting footage.

The pilot uses actual UI controls to:

1. Upload and reconstruct, select 243 output frames, then start from the source-camera path.
2. Add and retime five intermediate keys using the source-time table below.
3. Look through keys, make small sideways Shift-drags, and adjust the aim to retain the athlete and hoop.
4. Return to the overview, scrub the hold, and play the real grey-hole and magenta references.

`nba-glide` is **specific to the NBA3 full-event plate**. It reads the reconstructed torso point near
normalized source-image coordinate `(0.367, 0.435)` at frame 60, then uses genuine pointer gestures
to place it near `(0.40, 0.435)` during the hold. This preserves space for the ball and hoop rather
than aiming every key at the scene centre. It does not inject camera state or replace UI responses.
Read-only projection calculations guide the automated gestures; this is not an automatic subject-tracking feature.

Nominal sideways offsets reach 0.024 scene-centre-depth units, with no forward push. Exact positions
and aims are retained in `path_preview.json`; these depth-normalized units are not metres.
The older nominal 30° orbit workflow remains available as `--camera-style orbit-pilot` (the script's
default for compatibility), **not as the recommended NBA3 path**. Neither workflow is a
reproduction of an approved CLI take, a large-angle benchmark or a guarantee of generated quality.
Inspect both downloaded reference videos continuously before spending time on final generation.
Passing the Studio's clearance gate is not a visual-quality verdict.

To capture the same scripted workflow **including a new generated take**, use a new directory and
add `--render`:

```bash
"$PY" docs/record_studio_walkthrough.py \
  --source videos-all/nba3_teacher30/nba3_full_event.mp4 \
  --camera-style nba-glide \
  --out videos-all/studio_walkthrough/nba3_render_01 \
  --render
```

This is a new session, not a resume of the preview. The script retains and checks the accepted job's
payload against the path displayed in **that recording**. It never bypasses a disabled Render button.
Add `--headed` to watch in Chromium on a machine with a display; let the automation finish without
editing the same page. Default headless mode records the same viewport without needing a desktop.
`--timeout` sets each backend wait in seconds; the default is 1800. A timeout or closed browser
**does not cancel an already submitted job**. Check its recorded job ID before retrying.

If Playwright or Chromium is missing, install them in the recording environment first:

```bash
"$PY" -m pip install playwright
"$PY" -m playwright install chromium
```

### What gets saved

- `studio_walkthrough_raw.webm`: the actual 1920 × 1080 browser viewport, **including real waits**.
  It records neither browser chrome nor audio; do not rely on it to include the OS mouse cursor.
  No fake cursor, replacement UI, simulated responses or accelerated preview are injected.
- `input.*` and, when present, `input_provenance.json`: a retained upload and its adjacent source record.
- `prepared.json`, `path_preview.json`, `warp_preview.json`: the normalized span, geometry, exact
  edited keys, source-frame map and preview diagnostics. Preview-only runs do not claim a render payload.
- `preview_truth.mp4`, `preview_holes.mp4`, numbered screenshots: reference footage and review stills.
- With `nba-glide`, `subject_anchor.json`: the selected reconstructed torso point and its source projection.
- `session.json`, `studio_served.html`: source/download hashes, served UI, request payloads and
  client-observed wall-clock milestones. These timestamps are relative to script startup, **not exact
  WebM edit points or an interactive-latency benchmark**.
- With `--render`: `render_request.json`, `job.json`, and the matching `source.mp4`, `render.mp4`,
  `out.mp4`, `grid.mp4`. `source.mp4` follows the authored source-time map; it is not the untouched input.

The API does not expose checkpoint identities or the launch recipe. Retain the service launch command,
checkpoint/adapter identifiers and server log separately. Also preserve the normalized upload from
`<service --work>/clips/<clip>/clip.mp4` if an exact input archive is needed; `<clip>` is recorded in
`prepared.json`. The script does not inspect the server filesystem or guess its configuration.

For an MP4 viewing copy, without cutting waits or changing playback speed:

```bash
ffmpeg -n -i videos-all/studio_walkthrough/nba3_render_01/studio_walkthrough_raw.webm \
  -c:v libx264 -crf 18 -pix_fmt yuv420p -movflags +faststart \
  videos-all/studio_walkthrough/nba3_render_01/studio_walkthrough_review.mp4
```

Keep the raw recording. A 45-second research-page film is a **separate editorial pass**, following
the outline below, with omitted waits disclosed. Use the downloaded full `out.mp4` for the cinematic
reveal, not a screen-recorded crop of its small comparison pane. Do not publish a Studio-film link
until the actual recording and generated motion have been reviewed.

## The story

**Design the observation. See the reference. Generate the shot.**

One beautiful source, one deliberate camera path, one uninterrupted generated result. Show that the
released Studio is an authoring tool—not only a gallery or a menu of orbit presets. The point is the
relationship between an edit and its visible consequence, rather than a tour of every control.

Place the film in the research article's Studio section, after the method and speed discussion.
Keep the cinematic hero separate: the hero shows the result; this film explains how to author it.

## Capture outline · approximately 45 seconds

These are editorial allocations, **not measured service timings**. Extend the capture if an operation
needs longer; do not speed up pointer movement or pretend the model generated instantaneously.

| Passage | Actual screen action | Minimal caption |
|---|---|---|
| Establish · 0–4 s | Show the chosen source, then the actual Studio with a prepared source span. The source must remain identifiable. | One source. A new observation. |
| Author · 4–16 s | Show the multi-key path, look through a key, Shift-drag sideways and adjust its aim. Keep the athlete and hoop legible; do not exaggerate the small travel. | Place the camera. Shape its path. |
| Shape time · 16–23 s | Show two keys sharing a source frame at different output frames. Scrub across the hold and the subsequent advancing segment. | Hold the moment. Keep the camera moving. |
| Inspect · 23–29 s | Let the genuine full-path warp finish. Play the grey-hole reference; briefly switch to the magenta diagnostic. Keep one actual edit-to-preview response at native speed. | Preview the geometry before generating. |
| Generate · 29–32 s | Click **Render this take** and show the real progress screen. If waiting is cut, say so and report the retained run's elapsed time. | Generation wait omitted: [measured duration]. |
| Reveal · 32–42.125 s | Play the matching 243-frame output intact at 24 fps, large and uncluttered. | Generated view. |
| Close · about 3 s | End on the Studio's source / reference / output comparison or a quiet wordmark. | Meridian Studio · included in the code release. |

The final take must be generated from **the exact Studio keys shown**. An existing CLI flower or
motorcycle output is useful for choosing a scene, but is not evidence of an unexecuted Studio path.

## Source and camera design

**NBA3 is the current walkthrough source.** Its wide view makes the approach, airborne ball sweep,
dunk and landing legible as one event. The retained 124-frame plate covers the full supplied clip;
its frame 60 maps to original frame 73 / PTS 2.435767 s. See the
[exact input preparation](../videos-all/nba3_teacher30/provenance.json). These are source-file
timestamps, not a claim about physical capture speed. The footage is user-supplied; public
redistribution rights and endorsement have not been established.

The *Spring* flower scene remains an alternate, with Blender Foundation attribution and CC BY 4.0
notice in [its input preparation](../videos-all/longtake_edit/plates/flowers_linger243.json).

Use a source export appropriate for the Studio's **maximum 124-frame prepared window**. Do not claim
the Studio reproduced a 243-source-frame CLI reconstruction; selecting a 243-frame *output* does
not enlarge its prepared source window. Begin with a modest, well-framed path. Only increase travel
after inspecting the projection—an impressive trajectory that loses the athlete is a worse demo.

For a 124-frame prepared span starting at `start`, this **timing sketch** fits a 243-frame output:

| Output index `t` | Source index | Camera intention, to tune in the actual scene |
|---|---|---|
| 0 | `start + 0` | Establish the source-side composition. |
| 40 | `start + 40` | Follow the source framing with a small lateral offset. |
| 60 | `start + 60` | Begin the time hold with breathing room around the subject. |
| 105 | `start + 60` | Glide sideways while retaining the athlete. |
| 145 | `start + 60` | Travel sideways, keeping the aim on the subject. |
| 179 | `start + 60` | Ease back toward the source-side camera before action resumes. |
| 242 | `start + 123` | Let the action advance again. |

This uses all 124 prepared source frames and adds 119 held output frames. It preserves the prepared
input's pace outside the hold; any slow motion already in that input remains baked in. The exact
camera keys are saved with each recording. This table specifies intent, not a promise of seamless
generated motion.

## What “real-time preview” may honestly mean

- **Browser 3D view:** a loaded point cloud and camera handles redraw during interaction. Capture
  this normally; do not attach an FPS or latency claim without measuring it.
- **Full-path geometric reference:** generated by the backend after a committed valid edit. This
  requires GPU work and video encoding; it can wait behind other service work.
- **Final generated video:** a separate render job. Never label its replay as a live model response.

The point-cloud overview is not the full conditioning tensor. The grey-hole video is a compressed
preview of that reference; the magenta view is diagnostic and is not given to the model.

## Capture and acceptance checklist

- Record the actual released `service/index.html`, not a UI mock or the `videos-all` gallery.
- Arrange a dedicated service/GPU recording slot separately. Do not interrupt existing jobs to make
  this recording. No service was started or render queued as part of this documentation update.
- Capture at native 1920 × 1080 or another readable desktop size. Keep pointer motion deliberate;
  show the key table when explaining source time. Avoid cinematic overlays on the actual output.
- Retain the source export, normalized frame window, exact `/render` path payload, seed, model
  recipe, output files and status timings alongside the raw capture. The UI has no path-export
  button, so retain the request through browser network tools or the client used for the session.
- Disclose omitted reconstruction/generation waits. Keep one representative edit-to-warp update
  unaccelerated, including its real waiting time. Cold reconstruction is not interactive preview.
- Check subject visibility, transitions into/out of the hold, thin geometry and newly exposed
  backgrounds continuously. Sampled frames and successful playback alone are insufficient.
- Confirm the generated take matches the recorded path and source map. Record any crops or omitted
  output frames; the first choice is to keep the complete generated take intact.
- Add source credits and transformation notices. Do not imply that a view inferred from a film is
  documentary footage, or that a nominal orbit angle was measured in the generated output.

Once recorded and reviewed, add a real poster and MP4 link to the research article. Until then,
link this plan explicitly as a plan; no broken “Watch Studio” button or fabricated placeholder video.