Update README with setup and publish documentation
This commit is contained in:
@@ -1,53 +1,198 @@
|
||||
# AmiReel
|
||||
|
||||
Windows WPF replacement for `amigadb-render.sh`. The first milestone implements:
|
||||
AmiReel is a Windows video-rendering tool for turning Amiga AVI captures into:
|
||||
|
||||
- multiple ordered AVI inputs;
|
||||
- 3840×2160 at 50 FPS;
|
||||
- automatic NVIDIA NVENC detection with libx264 fallback;
|
||||
- configurable trim, fade and end-card hold;
|
||||
- PNG/JPG screenshots at a configurable interval;
|
||||
- animated WebP screenshot preview;
|
||||
- optional custom paths for `ffmpeg.exe` and `ffprobe.exe`;
|
||||
- automatic FFmpeg library probing when shared `avformat`/`avutil` DLLs are present beside `ffmpeg.exe`;
|
||||
- non-fatal missing thumbnails;
|
||||
- live FFmpeg log, progress and cancellation;
|
||||
- one-file Windows publishing with embedded FFmpeg and FFprobe.
|
||||
- a 4K 50 FPS final video,
|
||||
- PNG/JPG thumbnails,
|
||||
- an animated WebP preview,
|
||||
- and a publishable Windows desktop app workflow.
|
||||
|
||||
## Build
|
||||
The repository currently contains two desktop frontends that share the same render pipeline:
|
||||
|
||||
Requirements:
|
||||
- `AmiReel.WinUI`
|
||||
The newer WinUI 3 application. This is the default publish target.
|
||||
- `AmigaDB.VideoRenderer.csproj`
|
||||
The existing WPF application.
|
||||
|
||||
- Windows 10/11 x64
|
||||
- .NET 8 SDK
|
||||
- matching Windows x64 `ffmpeg.exe` and `ffprobe.exe` in `ThirdParty`
|
||||
## Features
|
||||
|
||||
Development build (does not require FFmpeg until render is started):
|
||||
- multiple ordered AVI inputs
|
||||
- 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
|
||||
- FFmpeg log output
|
||||
- source video preview and final render preview
|
||||
- dark and light themes
|
||||
- optional custom `ffmpeg.exe` / `ffprobe.exe` paths
|
||||
- automatic FFmpeg detection from `PATH`
|
||||
- single-file WinUI publish for easier distribution
|
||||
|
||||
## Requirements
|
||||
|
||||
For development:
|
||||
|
||||
- Windows 10 or Windows 11
|
||||
- .NET SDK
|
||||
- WPF project: .NET 8 SDK
|
||||
- WinUI project: .NET 10 SDK and WinUI/Windows App SDK support
|
||||
- Windows x64 FFmpeg binaries in `ThirdParty`
|
||||
- `ThirdParty\ffmpeg.exe`
|
||||
- `ThirdParty\ffprobe.exe`
|
||||
|
||||
For end users:
|
||||
|
||||
- Windows 10 or Windows 11 x64
|
||||
- the published AmiReel executable
|
||||
- FFmpeg is not required separately if you distribute AmiReel with embedded `ThirdParty` FFmpeg binaries
|
||||
|
||||
## Project Layout
|
||||
|
||||
- `AmiReel.WinUI\`
|
||||
WinUI 3 frontend
|
||||
- `MainWindow.xaml` and `MainWindow.xaml.cs`
|
||||
WPF frontend
|
||||
- `Services\RenderPipeline.cs`
|
||||
Main render workflow
|
||||
- `Services\ProcessRunner.cs`
|
||||
FFmpeg process execution and progress parsing
|
||||
- `Services\ToolExtractor.cs`
|
||||
FFmpeg resolution, extraction, and fallback logic
|
||||
- `publish-win-x64.ps1`
|
||||
Publish script
|
||||
|
||||
## Run in Development
|
||||
|
||||
### WinUI
|
||||
|
||||
```powershell
|
||||
dotnet build .\AmiReel.WinUI\AmiReel.WinUI.csproj
|
||||
dotnet run --project .\AmiReel.WinUI\AmiReel.WinUI.csproj
|
||||
```
|
||||
|
||||
### WPF
|
||||
|
||||
```powershell
|
||||
dotnet build .\AmigaDB.VideoRenderer.csproj
|
||||
dotnet run --project .\AmigaDB.VideoRenderer.csproj
|
||||
```
|
||||
|
||||
Portable publish:
|
||||
## Publish
|
||||
|
||||
### Default: WinUI
|
||||
|
||||
The publish script now defaults to the WinUI application:
|
||||
|
||||
```powershell
|
||||
.\publish-win-x64.ps1
|
||||
```
|
||||
|
||||
The publish target intentionally fails when either FFmpeg executable is absent,
|
||||
preventing creation of an application that cannot render.
|
||||
This publishes the WinUI app as a self-contained single-file executable.
|
||||
|
||||
## Distribution and FFmpeg
|
||||
At the end of the script you will see:
|
||||
|
||||
The application embeds the selected FFmpeg binaries and extracts them into its
|
||||
private local runtime cache. Include the license and source/build offer required
|
||||
by the exact FFmpeg distribution you choose. Do not remove its copyright and
|
||||
licensing notices.
|
||||
- the release folder path
|
||||
- the final executable path
|
||||
|
||||
If you prefer not to use the embedded binaries at runtime, you can point the UI
|
||||
at external `ffmpeg.exe` and `ffprobe.exe` files. Those paths are saved in the
|
||||
user settings file under `%LOCALAPPDATA%\AmiReel\settings.json`.
|
||||
Example output path:
|
||||
|
||||
If the selected FFmpeg folder also contains shared FFmpeg DLLs such as
|
||||
`avformat-*.dll` and `avutil-*.dll`, AmiReel will use those libraries for media
|
||||
probing in place of `ffprobe.exe` while keeping rendering on `ffmpeg.exe`.
|
||||
```text
|
||||
AmiReel.WinUI\bin\Release\net10.0-windows10.0.26100.0\win-x64\publish\AmiReel.exe
|
||||
```
|
||||
|
||||
### Publish WPF instead
|
||||
|
||||
```powershell
|
||||
.\publish-win-x64.ps1 -Target Wpf
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### For developers
|
||||
|
||||
1. Clone the repository.
|
||||
2. Add `ffmpeg.exe` and `ffprobe.exe` to `ThirdParty`.
|
||||
3. Restore and build the desired app:
|
||||
|
||||
```powershell
|
||||
dotnet build .\AmigaDB.VideoRenderer.sln
|
||||
```
|
||||
|
||||
4. Run either the WinUI or WPF project.
|
||||
|
||||
### For end users
|
||||
|
||||
1. Copy the published `AmiReel.exe` from the publish folder to any location, for example:
|
||||
|
||||
```text
|
||||
C:\Apps\AmiReel\
|
||||
```
|
||||
|
||||
2. Double-click `AmiReel.exe`.
|
||||
3. If FFmpeg is embedded in the build, no extra setup is required.
|
||||
4. If you want to use your own FFmpeg build:
|
||||
open `Settings` and select:
|
||||
- `ffmpeg.exe`
|
||||
- `ffprobe.exe`
|
||||
|
||||
### Optional desktop shortcut
|
||||
|
||||
1. Right-click `AmiReel.exe`.
|
||||
2. Choose `Send to` -> `Desktop (create shortcut)`.
|
||||
|
||||
## FFmpeg Behavior
|
||||
|
||||
AmiReel resolves FFmpeg in this order:
|
||||
|
||||
1. custom paths from settings
|
||||
2. `ffmpeg.exe` and `ffprobe.exe` found on system `PATH`
|
||||
3. embedded `ThirdParty` binaries
|
||||
|
||||
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 values such as:
|
||||
|
||||
- output folder
|
||||
- end-card path
|
||||
- FFmpeg paths
|
||||
- theme
|
||||
- encoder selection
|
||||
- timing settings
|
||||
|
||||
## 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 FFmpeg 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.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### App falls back to CPU instead of NVENC
|
||||
|
||||
This usually means FFmpeg could not initialize `h264_nvenc`. AmiReel will continue with CPU encoding automatically.
|
||||
|
||||
### FFmpeg tool error
|
||||
|
||||
If embedded FFmpeg is missing or broken, AmiReel will try:
|
||||
|
||||
1. configured tool paths
|
||||
2. FFmpeg from `PATH`
|
||||
|
||||
If needed, set the paths manually in `Settings`.
|
||||
|
||||
### Render failed popup
|
||||
|
||||
The popup shows a short human-readable summary. Full technical details remain available in the `FFmpeg log` panel.
|
||||
|
||||
## Current Default Recommendation
|
||||
|
||||
Use the WinUI build for publishing and distribution unless you specifically need the WPF variant.
|
||||
|
||||
Reference in New Issue
Block a user