AmiReel/README.md

# AmiReel

AmiReel is a Windows desktop app for turning Amiga (or any) screen recordings into:

- a 4K 50 FPS final video,
- PNG/JPG thumbnails,
- an animated WebP preview.

Built with **WinUI 3** on the Windows App SDK, driving FFmpeg under the hood.

## Features

- Multiple ordered video inputs — `.avi`, `.mp4`, `.m4v`, `.mov`, `.mkv`, `.webm`, `.wmv`, `.flv`, `.mpg`, `.mpeg`, `.ts`, `.3gp`
- Drag-and-drop or file-picker source selection
- 3840×2160 output at 50 FPS
- NVIDIA NVENC with automatic CPU `libx264` fallback
- Configurable trim, fade, end-card hold, and thumbnail interval
- Optional end-card image
- Live render progress with frame counters and FFmpeg log output
- Source and final-render preview (built-in or a custom player)
- Dark and light themes
- Optional move of source recordings into `originals/` in the output folder
- Optional custom `ffmpeg.exe` / `ffprobe.exe` paths, with automatic detection from `PATH`
- Self-contained single-file publish for easy distribution

## Project Layout

```
AmiReel.csproj              Project file
AmiReel.slnx                Solution file
App.xaml(.cs)                Application entry point
MainWindow.xaml(.cs)         Window shell: custom title bar, theming, exit confirmation
MainPage.xaml(.cs)           Main UI: source list, settings, render controls
DialogHelper.cs              Shared ContentDialog styling (Settings, exit, error dialogs)
Package.appxmanifest         MSIX packaging identity and tile/icon declarations
app.manifest                 Win32 manifest (DPI awareness, OS compatibility)
Assets/                      Packaged app icons and tiles (all required sizes)
branding/                    Source artwork the Assets/ tiles are generated from
Models/
  AppSettings.cs              Persisted user settings
  RenderSettings.cs           Render job parameters
  SupportedVideoFormats.cs    Accepted input file extensions
Services/
  RenderPipeline.cs           Main render workflow (FFmpeg orchestration)
  ProcessRunner.cs            FFmpeg process execution and progress parsing
  FfmpegProgressParser.cs     Parses time=/frame=/fps=/speed= from FFmpeg output lines
  FfmpegOutputFilter.cs       Shared FFmpeg banner/boilerplate line filtering
  ToolExtractor.cs            FFmpeg resolution, extraction, and fallback logic
  MediaProbe.cs                Duration/audio-stream probing via ffprobe
  FfmpegLibraryProbe.cs        NVENC capability probing
  AppSettingsStore.cs          Settings load/save (JSON in %LOCALAPPDATA%)
  UserFacingErrors.cs          Exception-to-message translation
Properties/
  AssemblyInfo.cs              InternalsVisibleTo AmiReel.Tests
  launchSettings.json
  PublishProfiles/             win-x64/x86/arm64 publish profiles
AmiReel.Tests/                Unit tests (MSTest), mirrors Models/ and Services/
ThirdParty/                  Embedded ffmpeg.exe / ffprobe.exe (not checked in, see below)
publish-win-x64.ps1          Publish script
```

## Requirements

For development:

- Windows 10 or Windows 11
- .NET 10 SDK with WinUI 3 / Windows App SDK workload
- Windows x64 FFmpeg binaries in `ThirdParty/`:
  - `ThirdParty\ffmpeg.exe`
  - `ThirdParty\ffprobe.exe`

For end users:

- Windows 10 or Windows 11 x64
- The published `AmiReel.exe` — FFmpeg is not required separately if you distribute AmiReel with the embedded `ThirdParty` binaries

## Run in Development

```powershell
dotnet build .\AmiReel.csproj
dotnet run --project .\AmiReel.csproj
```

## Run Tests

Unit tests live in `AmiReel.Tests/` (MSTest), covering the pure logic in `Models/` and
`Services/` — settings normalization, supported-format detection, FFmpeg output parsing/
filtering, render-settings validation, and moving source files into `originals/`.

```powershell
dotnet test .\AmiReel.Tests\AmiReel.Tests.csproj
```

UI code-behind (`App`, `MainWindow`, `MainPage`) and anything that spawns an actual FFmpeg
process are intentionally left to manual/integration testing rather than unit tests.

## Publish

```powershell
.\publish-win-x64.ps1
```

This publishes a self-contained, single-file `win-x64` executable. At the end of the script
you'll see the release folder and final executable path, for example:

```text
bin\Release\net10.0-windows10.0.26100.0\win-x64\publish\AmiReel.exe
```

## Installation

### For developers

1. Clone the repository.
2. Add `ffmpeg.exe` and `ffprobe.exe` to `ThirdParty\`.
3. Restore and build:

```powershell
dotnet build .\AmiReel.slnx
```

### For end users

1. Copy the published `AmiReel.exe` to any location, for example `C:\Apps\AmiReel\`.
2. Double-click `AmiReel.exe`.
3. If FFmpeg is embedded in the build, no extra setup is required.
4. To use your own FFmpeg build instead, open **Settings** and set:
   - `ffmpeg.exe` path
   - `ffprobe.exe` path

### Optional desktop shortcut

Right-click `AmiReel.exe` → **Send to** → **Desktop (create shortcut)**.

## FFmpeg Behavior

AmiReel resolves FFmpeg in this order:

1. Custom paths from Settings
2. `ffmpeg.exe` / `ffprobe.exe` found on the system `PATH`
3. Embedded `ThirdParty` binaries (extracted to `%LOCALAPPDATA%\AmiReel\tools` on first use)

If NVENC cannot be initialized, AmiReel automatically falls back to CPU `libx264`.

## Settings Location

User settings are stored in:

```text
%LOCALAPPDATA%\AmiReel\settings.json
```

This includes: output folder, end-card path, FFmpeg/preview-player paths, theme, encoder
selection, timing settings, and whether source videos are moved into `originals/` after a
successful render.

## Notes for Distribution

- If you distribute FFmpeg binaries with AmiReel, you are responsible for complying with the
  license terms of the FFmpeg build you use. Keep any required notices, source offer, or
  attribution required by that distribution.
- Windows Explorer may cache executable icons. If a freshly published build still shows an old
  icon, rename the file or refresh the icon cache before assuming the embed failed.
- `Package.appxmanifest` currently has a placeholder `Identity` (a random GUID `Name` and
  `Publisher="CN=AppPublisher"`). That's fine for local unpackaged builds, but before signing
  an MSIX for real distribution, replace them with a real publisher identity and generate a
  matching signing certificate (`winapp cert generate`, see `AGENTS.md`).

## Troubleshooting

**App falls back to CPU instead of NVENC** — FFmpeg could not initialize `h264_nvenc`. AmiReel
continues automatically with CPU encoding.

**FFmpeg tool error** — If the embedded FFmpeg is missing or broken, AmiReel tries configured
tool paths, then FFmpeg from `PATH`. Set the paths manually in **Settings** if needed.

**Render failed popup** — Shows a short human-readable summary. Full technical details remain
available in the **FFmpeg log** panel.