# Interactive Video — first version

Interactive Video is the ninth activity in the existing H5P chooser. It uses the official H5P.InteractiveVideo 1.28.37 library and the existing standalone 3.8.2 runtime. The original 33 catalog pins are unchanged; 25 additional libraries are pinned by their file-inventory hashes. The official acquisition URL and bundle hash are recorded in `resources/h5p-libraries.lock.json` in the backend.

## Authoring

1. Open **H5P → Add activity → Interactive Video**.
2. Upload a video or select a previously uploaded project video.
3. Play/pause at the desired moment and choose **Add here**.
4. Choose **Question**, **True / False**, or **Information**.
5. Preview the saved activity using the existing activity/course preview controls.

Questions show a prompt, answers, and a correct-answer selector. Feedback and solution controls are under **More settings**. Questions pause the video and playback continues after the learner checks an answer. Information appears as a button and supports an optional image. Numeric MM:SS fields, timeline markers, duplication, removal, and a larger editor are provided. The English and Arabic interfaces follow the existing language setting; native H5P playback retains the independent H5P number-format setting.

**Video settings** contains the optional poster, English/Arabic WebVTT tracks, and forward-seeking restriction. Completion is fixed for this version: reach the video end and answer every question, regardless of whether the answers are correct. Activity score is the fraction of questions answered correctly; existing course grading policy is unchanged.

## Limits and portability

- MP4 with H.264 8-bit 4:2:0 video and AAC audio (or no audio), up to 100 MiB and 24 hours. Files are validated with FFprobe. Other codecs must be converted before upload; this version does not transcode them.
- Up to 20 interactions per video; new multiple-choice questions offer up to six answers and one correct answer.
- Up to one English and one Arabic caption track. UTF-8 WebVTT, plain text cues, up to 1 MiB per track. Rich HTML cue markup is not supported.
- Existing project storage limits still apply. Large binary uploads remain separate from the H5P document JSON.
- Video/caption previews use project authorization or expiring preview signatures. Binary file responses support byte-range seeking.
- Native content and all referenced video, image, caption, runtime and library files are bundled using relative paths in SCORM exports. Editable-project archives preserve/remap the new asset references and duration metadata.
- SCORM resume stores playback position, answered/correct question masks, completion and score. It does not restore the detailed selected answer UI or feedback history. Content revision changes invalidate the previous activity state. Legacy non-video progress remains supported.
- The `h2` progress envelope adds 17 bytes per video before Base64 encoding. Both package preflight and the runtime enforce the combined 4,096-character suspend-data budget. Existing courses without video retain `h1` encoding.
- External video platforms, adaptive jumps, additional interaction types and end-summary authoring are deferred.

Video asset integrity checks, native content generation and large file copies happen before the H5P document lock. The document revision is checked again under the lock before committing the prepared content.

## Installation / release

Local installation has applied only the additive `2026_11_16_100000_add_h5p_video_duration.php` migration and installed the new pinned library dependencies. No database reset or business-data migration is needed.

For another installation, preserve `.env`, `APP_KEY`, the database and private storage. With the correct PHP selected:

```powershell
cd documents_generator_tools_frontend
npm ci
npm run sync:h5p-libraries
npm run build
cd ../documents_generator_tools_backend
php artisan migrate --force
php artisan h5p:setup
php artisan h5p:check
```

Ensure FFprobe is available, configure `FFPROBE_BINARY` if necessary, and allow the selected upload size in PHP and the web/proxy server. `H5P_MAX_VIDEO_UPLOAD_KB` defaults to 102400. Clear cached configuration and restart the relevant long-lived workers as part of the normal release process. Production/Moodle acceptance must be performed on the destination; local tests do not establish production readiness.

## Validation

The backend integration tests use the real pinned libraries and a generated 12-second MP4. They exercise upload validation, private seeking previews, WebVTT delivery, server-owned duration, native subcontent IDs, incomplete drafts, package contents, and editable-project archive round trips. Frontend tests cover the three-choice editor, timing, duplication/removal, activity completion isolation, native video end events, revision isolation, compact resume and legacy progress.

Run backend tests directly with SQLite enabled (the Artisan test subprocess does not inherit CLI `-d` flags):

```powershell
php -d extension=pdo_sqlite -d extension=sqlite3 vendor/bin/phpunit --filter="H5pStudioTest|ProjectArchiveTest"
```

For synthetic browser fixture output only, set `H5P_VIDEO_WRITE_ACCEPTANCE=1` when running `test_interactive_video_upload`. It writes the portable activity files to backend `storage/app/private/h5p-iv-review/offline`, using only the in-memory test database. This is not a production export path.
