# AGILAB Video Tutorial And Slideshow Guide

Use this guide when you want to produce a short AGILAB tutorial package instead of
an isolated video file.

The package has three complementary assets:

- a short live tutorial video or GIF
- a self-generated explainer MP4/GIF/poster
- a static slideshow/visual kit for README, docs, and launch posts

## Recommended tutorial package

Keep one app per video, but support two stable narrative packs:

- `flight_project`
  - safest default
  - best for newcomer onboarding
  - easiest to keep aligned with the existing README/slideshow story
- `UAV Relay Queue` (`uav_relay_queue_project`)
  - stronger novelty and more visible `ANALYSIS`
  - best when you want a more technical and more memorable queueing demo

Default recommendation:

- use `flight_project` for the main AGILAB intro video
- use `UAV Relay Queue` (`uav_relay_queue_project`) as the second product demo when
  you want a more specialized "wow" path

Core assets already in the repo:

- `docs/source/diagrams/agilab_readme_tour.svg`
- `docs/source/diagrams/agilab_social_card.svg`
- `artifacts/demo_media/agilab_explainer.gif`
- `artifacts/demo_media/agilab_explainer.mp4`
- `artifacts/demo_media/agilab_explainer_poster.png`

The key message should stay consistent across all three formats:

`One app, one control path from PROJECT to ORCHESTRATE to PIPELINE to ANALYSIS.`

## Which format to use

Use a live tutorial when you want to show the real UI flow:

- selecting the app
- launching orchestration
- inspecting pipeline steps
- ending on analysis results

Use the self-generated explainer when you want a lightweight shareable asset:

- launch posts
- README/social embeds
- quick product intros

Use the slideshow/static kit when you need a narrated talk track without video:

- one presenter slide
- one README figure
- one poster frame

## Fastest live workflow

Concrete capture command for the default `flight_project` tutorial:

```bash
tools/capture_demo_workflow.sh --name agilab-flight --duration 45 --trim 30
```

Concrete capture command for the `uav_relay_queue_project` variant:

```bash
tools/capture_demo_workflow.sh --name agilab-uav-queue --duration 60 --trim 45
```

This wrapper:

- launches an interactive macOS screen recording with `screencapture`
- stores the raw `.mov` under `artifacts/demo_media/<name>/raw/`
- exports a shareable `.mp4` and `.gif` under `artifacts/demo_media/<name>/edited/`

If you already have a raw recording and only want the export step:

```bash
uv --preview-features extra-build-dependencies run --with imageio-ffmpeg \
  python tools/export_demo_media.py \
  --input artifacts/demo_media/agilab-flight/raw/example.mov \
  --mp4 artifacts/demo_media/agilab-flight/edited/agilab-flight.mp4 \
  --gif artifacts/demo_media/agilab-flight/edited/agilab-flight.gif \
  --duration 30
```

## Self-generated fallback

Use this when you do not want to rely on interactive capture:

```bash
uv --preview-features extra-build-dependencies run --with imageio --with imageio-ffmpeg \
  python tools/build_demo_explainer.py
```

This produces:

- `artifacts/demo_media/agilab_explainer.gif`
- `artifacts/demo_media/agilab_explainer.mp4`
- `artifacts/demo_media/agilab_explainer_poster.png`

## Storyboard

### Flight 30-second version

Use this when you want a quick social/demo clip.

1. Show the AGILAB home screen.
2. Show `flight_project` selected in `PROJECT`.
3. Jump to `ORCHESTRATE` and trigger the run path.
4. Show `PIPELINE` with generated/replayable steps.
5. End in `ANALYSIS` on a visible result.

Narration:

`AGILAB gives one app a single control path from selection to execution to analysis.`

### Flight 45-second version

Use this as the default product tutorial.

1. Open AGILAB.
2. Select `src/agilab/apps/builtin/flight_project` in `PROJECT`.
3. Briefly show app settings or source context.
4. Move to `ORCHESTRATE`.
5. Trigger install, distribute, and run.
6. Show that the workflow is packaged and executed without ad-hoc shell glue.
7. Move to `PIPELINE`.
8. Show generated or replayable steps.
9. Move to `ANALYSIS`.
10. End on a built-in page over produced artifacts.

Narration:

`Instead of hand-wiring environments, scripts, and checks, AGILAB gives the same app one controlled path from UI to workers to analysis.`

### Flight 60-second version

Use this only when you need a slightly more explanatory walkthrough.

Keep the same path, but add one explicit sentence on each stage:

- `PROJECT` defines the app and settings
- `ORCHESTRATE` packages and runs the workflow
- `PIPELINE` makes the steps inspectable and replayable
- `ANALYSIS` ends on visible evidence

Do not add a second app. Do not branch into alternative flows.

### Flight 3-minute version

Use this when you want a narrated product walkthrough that still stays aligned
with the existing `AGILAB 3-minute tour` figure.

Keep the same single-app path:

1. `PROJECT`
2. `ORCHESTRATE`
3. `PIPELINE`
4. `ANALYSIS`

Do not introduce a second app, an alternative branch, or a second execution
mode. The extra time is for clarity, not breadth.

Suggested timeline:

1. `0:00 -> 0:20`
   Open the AGILAB home screen and state the single message:
   `one app, one control path from project selection to execution to analysis.`
2. `0:20 -> 0:50`
   Go to `PROJECT`, select `src/agilab/apps/builtin/flight_project`, and show
   that the app already carries its own arguments, pages, and outputs.
3. `0:50 -> 1:35`
   Move to `ORCHESTRATE`, show the install / distribute / run areas, and
   explain that AGILAB generates the operational snippet instead of asking the
   user to hand-wire the workflow first.
4. `1:35 -> 2:05`
   Move to `PIPELINE`, show the generated or replayable step, and explain that
   the same execution path can now be inspected, rerun, and tracked as part of
   the lab workflow.
5. `2:05 -> 2:40`
   Move to `ANALYSIS`, open a visible result page, and show that the run ends
   on an operator-facing view rather than raw infrastructure logs.
6. `2:40 -> 3:00`
   Return to the core message and close on the same app/result:
   `AGILAB keeps one app on one coherent path from setup to evidence.`

Suggested narration:

`This is AGILAB in one path. In PROJECT, I select the app and keep its context.
In ORCHESTRATE, AGILAB packages and runs the workflow without ad-hoc shell glue.
In PIPELINE, the same execution becomes inspectable and replayable. In ANALYSIS,
the workflow ends on visible evidence, not just logs. The point is not another
generic DAG. The point is one app, one controlled path, from setup to result.`

Suggested click path:

1. Home page
2. `PROJECT`
3. app selector -> `flight_project`
4. one short pause on app context
5. `ORCHESTRATE`
6. one short pause on generated install / run area
7. `PIPELINE`
8. one short pause on generated or imported step
9. `ANALYSIS`
10. final pause on a visible result

If you need a static deck with the same message, keep the slideshow sequence
below unchanged and use the 3-minute talk track above as the narration layer.

### UAV queue 45-second version

Use this when you want a technically stronger demo without changing the core
AGILAB message.

Keep the same page order:

1. `PROJECT`
2. `ORCHESTRATE`
3. `PIPELINE`
4. `ANALYSIS`

Suggested flow:

1. Open AGILAB.
2. Select `src/agilab/apps/builtin/uav_relay_queue_project` in `PROJECT`
   (`UAV Relay Queue`).
3. Briefly show the routing policy and scenario file.
4. Move to `ORCHESTRATE`.
5. Trigger the run.
6. Move to `PIPELINE`.
7. Show that the run is now replayable as a tracked step.
8. Move to `ANALYSIS`.
9. Open `view_uav_relay_queue_analysis`.
10. End on queue buildup, drops, or route usage.

Narration:

`AGILAB can also turn a lightweight UAV routing experiment into a reproducible
workflow. The point is still the same: one app, one control path, ending on a
visible analysis result.`

### UAV Relay Queue 3-minute version

Use this when you want the more memorable technical demo.

Do not mix it with `flight_project` in the same video. The clarity rule still
holds: one app, one path.

Suggested timeline:

1. `0:00 -> 0:20`
   Open the AGILAB home screen and state the goal:
   `turn a queueing experiment into a reproducible workflow.`
2. `0:20 -> 0:55`
   Go to `PROJECT`, select `src/agilab/apps/builtin/uav_relay_queue_project`
   (`UAV Relay Queue`), and show the scenario file plus the routing policy
   selector.
3. `0:55 -> 1:35`
   Move to `ORCHESTRATE`, launch the run, and explain that AGILAB takes a
   lightweight simulator-backed app and packages it into a controlled execution
   path.
4. `1:35 -> 2:00`
   Move to `PIPELINE`, show the generated or replayable step, and explain that
   the experiment is now explicit instead of being buried in one-off scripts.
5. `2:00 -> 2:40`
   Move to `ANALYSIS`, open `view_uav_relay_queue_analysis`, and show queue
   timeseries, drops, and routing summary.
6. `2:40 -> 3:00`
   Optionally open `view_maps_network` or end on the queue page, then close on:
   `AGILAB keeps the experiment reproducible all the way to visible evidence.`

Suggested narration:

`This is the more technical AGILAB story. In PROJECT, I choose a UAV queueing
experiment and its routing policy. In ORCHESTRATE, AGILAB runs it without
ad-hoc glue. In PIPELINE, the execution becomes replayable. In ANALYSIS, I land
on queue buildup, packet drops, and route usage. The point is not only to run a
simulation. The point is to turn it into a controlled, inspectable workflow.`

Suggested click path:

1. Home page
2. `PROJECT`
3. app selector -> `uav_relay_queue_project` (`UAV Relay Queue`)
4. short pause on scenario and routing policy
5. `ORCHESTRATE`
6. short pause on run controls
7. `PIPELINE`
8. short pause on the explicit step
9. `ANALYSIS`
10. `view_uav_relay_queue_analysis`
11. optional final pause on `view_maps_network`

## Slideshow structure

If you want a static slideshow instead of a video, use this sequence:

1. `AGILAB 3-minute tour`
   - `docs/source/diagrams/agilab_readme_tour.svg`
2. `One app, one path`
   - `docs/source/diagrams/agilab_social_card.svg`
3. `Explainer poster`
   - `artifacts/demo_media/agilab_explainer_poster.png`
4. Optional closing frame
   - a screenshot from `ANALYSIS`

The slideshow should tell the same story as the video, not introduce extra claims.

For the `UAV Relay Queue` video (`uav_relay_queue_project` install id), reuse the same
opening AGILAB figure, but end the static sequence on screenshots from:

- `view_uav_relay_queue_analysis`
- optionally `view_maps_network`

## Recording and visual rules

- Record at `1440p` or `1080p`, then crop tightly.
- Keep the cursor slow and deliberate.
- Avoid typing during capture unless the command is the point.
- Use one app only. The point is clarity, not breadth.
- End on a visible result, not logs.
- Trim dead time during export instead of re-recording immediately.
- Keep the visible UI path aligned with the narration path.
- Prefer one strong sentence on screen rather than many small labels.

## Quality checklist

- each tutorial uses one app only
- the visible sequence is `PROJECT -> ORCHESTRATE -> PIPELINE -> ANALYSIS`
- the ending frame shows a result, not infrastructure noise
- the video and slideshow use the same message
- the social/static assets do not contradict the live capture
- the clip stays short enough to rewatch once without fatigue

## Default tagline

`AGILAB gives one app one control path from project selection to execution to analysis.`