Beyhan Oğur
13 KiB
GIF Recorder
**Referenced Files in This Document** - [GIFRecorderWindow.xaml](file://ClassicAssist/UI/Views/GIFRecorderWindow.xaml) - [GIFRecorderWindow.xaml.cs](file://ClassicAssist/UI/Views/GIFRecorderWindow.xaml.cs) - [GIFRecorderViewModel.cs](file://ClassicAssist/UI/ViewModels/GIFRecorderViewModel.cs) - [ShowGIFCaptureWindow.cs](file://ClassicAssist/Data/Hotkeys/Commands/ShowGIFCaptureWindow.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document explains the GIF Recorder tool integrated into ClassicAssist.Avalonia. It covers gameplay recording capabilities, animation export options, quality settings configuration, the recording interface, frame rate controls, and output format specifications. It also documents integration with hotkey commands for start/stop recording functionality, provides examples for recording different types of gameplay content, guidance on optimizing file sizes, exporting animations for tutorials or bug reports, performance considerations during recording, storage management, and best practices for using recorded GIFs in documentation, testing, and community sharing.
Project Structure
The GIF Recorder feature is implemented as a dedicated window with its view model and is accessible via a hotkey command. The key files are:
- View (XAML): Defines the user interface for recording controls and preview.
- Code-behind: Wires UI events to the view model and manages window lifecycle.
- View Model: Holds recording state, settings, and exposes commands to the UI.
- Hotkey Command: Provides keyboard shortcuts to open the recorder and control recording.
graph TB
subgraph "UI Layer"
XAML["GIFRecorderWindow.xaml"]
CodeBehind["GIFRecorderWindow.xaml.cs"]
VM["GIFRecorderViewModel.cs"]
end
subgraph "Hotkeys"
HKCmd["ShowGIFCaptureWindow.cs"]
end
HKCmd --> VM
XAML --> CodeBehind
CodeBehind --> VM
Diagram sources
Section sources
Core Components
- GIFRecorderWindow (View): Presents recording controls such as start/stop, frame rate selection, quality settings, and output path. It binds to the view model for live updates and previews.
- GIFRecorderViewModel (ViewModel): Manages recording state (idle, capturing, stopped), holds configuration (frame rate, quality, output directory), and exposes commands for starting/stopping recording and saving exports.
- ShowGIFCaptureWindow (Hotkey Command): Registers a hotkey that opens the GIF Recorder window, enabling quick access without navigating menus.
Key responsibilities:
- Recording lifecycle: Start capture, stop capture, finalize output.
- Settings persistence: Save and load frame rate, quality, and output location.
- UI binding: Update status indicators, enable/disable controls based on state.
- Hotkey integration: Open the recorder window from anywhere in the application.
Section sources
Architecture Overview
The GIF Recorder follows a standard MVVM pattern with a hotkey entry point:
- Hotkey Command triggers opening the recorder window.
- The Window’s code-behind initializes bindings and delegates actions to the ViewModel.
- The ViewModel orchestrates recording logic and persists settings.
sequenceDiagram
participant User as "User"
participant Hotkey as "ShowGIFCaptureWindow.cs"
participant Window as "GIFRecorderWindow.xaml.cs"
participant VM as "GIFRecorderViewModel.cs"
participant UI as "GIFRecorderWindow.xaml"
User->>Hotkey : Press configured hotkey
Hotkey->>Window : Open GIF Recorder Window
Window->>VM : Initialize bindings and state
User->>UI : Click "Start Recording"
UI->>VM : Invoke StartRecording()
VM-->>UI : Update status and controls
User->>UI : Click "Stop Recording"
UI->>VM : Invoke StopRecording()
VM-->>UI : Finalize output and show save dialog
Diagram sources
Detailed Component Analysis
GIFRecorderWindow (View)
Responsibilities:
- Define layout for recording controls (start/stop buttons, frame rate dropdown, quality slider/dropdown, output path selector).
- Bind UI elements to properties and commands in the ViewModel.
- Display real-time status (recording indicator, elapsed time, progress).
Common UI interactions:
- Start/Stop toggles update ViewModel state.
- Frame rate and quality changes immediately affect subsequent frames.
- Output path selection determines where GIF files are saved.
Best practices:
- Keep UI responsive by delegating heavy work to background tasks in the ViewModel.
- Provide clear feedback when recording starts/stops.
Section sources
GIFRecorderViewModel (ViewModel)
Responsibilities:
- Maintain recording state (Idle, Capturing, Stopped).
- Expose properties for frame rate, quality, and output directory.
- Implement commands for StartRecording and StopRecording.
- Handle file I/O for saving GIF outputs.
- Persist settings across sessions if applicable.
Data flow:
- UI commands invoke ViewModel methods.
- ViewModel updates bound properties to reflect state changes.
- On stop, ViewModel writes frames to an animated GIF at the selected path.
Error handling:
- Validate output path permissions.
- Handle disk full or write errors gracefully.
- Notify the user via UI-bound messages.
Optimization hooks:
- Adjust frame rate to balance smoothness vs. file size.
- Reduce color palette or dimensions for smaller files.
Section sources
ShowGIFCaptureWindow (Hotkey Command)
Responsibilities:
- Register a global or application-level hotkey.
- When triggered, open the GIF Recorder window.
- Ensure thread safety when invoking UI operations.
Integration notes:
- The command should not interfere with game input.
- Provide a default hotkey that can be remapped in hotkey settings.
Section sources
Class Diagram
classDiagram
class GIFRecorderViewModel {
+string Status
+bool IsRecording
+int FrameRate
+string Quality
+string OutputPath
+StartRecording()
+StopRecording()
+SaveSettings()
+LoadSettings()
}
class GIFRecorderWindow {
+InitializeBindings()
+OnStartClicked()
+OnStopClicked()
}
class ShowGIFCaptureWindow {
+RegisterHotkey()
+OpenRecorderWindow()
}
GIFRecorderWindow --> GIFRecorderViewModel : "binds to"
ShowGIFCaptureWindow --> GIFRecorderWindow : "opens"
Diagram sources
Dependency Analysis
- The hotkey command depends on the window to open the UI.
- The window depends on the view model for behavior and state.
- The view model may depend on file system APIs for saving GIFs and possibly on configuration services for persisting settings.
graph LR
HK["ShowGIFCaptureWindow.cs"] --> Win["GIFRecorderWindow.xaml.cs"]
Win --> VM["GIFRecorderViewModel.cs"]
VM --> FS["File System / Storage"]
VM --> CFG["Configuration / Options"]
Diagram sources
Section sources
Performance Considerations
- Frame Rate: Lower frame rates reduce CPU usage and file size but may appear choppy. Choose a balance appropriate for the content type.
- Quality Settings: Reducing color depth or resolution significantly decreases file size; consider these for long recordings.
- Threading: Perform encoding and file I/O off the UI thread to keep the interface responsive.
- Memory Management: Avoid retaining large buffers; process frames incrementally and release resources promptly.
- Disk I/O: Use buffered writes and ensure sufficient free space; monitor disk usage to prevent interruptions.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Hotkey does not open the recorder: Verify the hotkey registration and ensure no conflicts with other inputs. Check the command’s activation path.
- Recording fails to start: Confirm the output path is writable and has enough space. Validate that the UI is bound correctly to the ViewModel.
- Large file sizes: Reduce frame rate and quality settings; consider shorter clips or cropping the capture area.
- Corrupted GIF output: Ensure the encoder completes writing all frames and flushes buffers before closing the file.
Operational checks:
- Inspect ViewModel state transitions (Idle -> Capturing -> Stopped).
- Validate UI bindings for Start/Stop commands and property updates.
- Review error notifications and logs for file system exceptions.
Section sources
Conclusion
The GIF Recorder integrates seamlessly with ClassicAssist.Avalonia through a clean MVVM architecture and a convenient hotkey entry point. By tuning frame rate and quality settings, users can optimize recordings for various use cases—from concise bug reports to detailed tutorials. Proper performance practices and storage management ensure reliable operation even during extended sessions.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Recording Interface Controls
- Start/Stop: Toggle recording session.
- Frame Rate: Select desired FPS for smoothness vs. size trade-off.
- Quality: Adjust color depth/resolution to manage file size.
- Output Path: Choose destination directory for saved GIFs.
Section sources
Hotkey Integration Examples
- Default hotkey opens the recorder window instantly.
- Remap the hotkey in hotkey settings to avoid conflicts.
- Combine with in-game macros to automate repetitive recording tasks.
Section sources
Export and Usage Guidance
- Tutorials: Use moderate frame rates and higher quality for clarity.
- Bug Reports: Short clips with reduced quality to minimize upload size.
- Community Sharing: Balance quality and size; include descriptive filenames and timestamps.
[No sources needed since this section provides general guidance]