### Start Method

Source: https://github.com/surgeonix/flyleaf/wiki/Engine

Initiates the startup process of the system.

```APIDOC
## Start Method

### Description
Initiates the startup sequence for the application or a specific module.

### Method
POST

### Endpoint
/start
```

--------------------------------

### Initialize Flyleaf Engine and Host in WinUI 3

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates the setup of the Flyleaf engine in App.xaml.cs and the integration of the FlyleafHost control within a FullScreenContainer in WinUI 3. It includes configuration for FFmpeg paths and UI refresh settings.

```csharp
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        Engine.Start(new EngineConfig()
        {
            FFmpegPath = @"C:\Flyleaf\FFmpeg",
            FFmpegDevices = false,
            #if DEBUG
            FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Warn,
            LogLevel = LogLevel.Debug,
            LogOutput = ":debug",
            #else
            FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Quiet,
            LogLevel = LogLevel.Quiet,
            #endif
            UIRefresh = true,
            UIRefreshInterval = 250
        });
    }
}
```

```xml
<Window xmlns:fl="using:FlyleafLib.Controls.WinUI">
    <Grid x:Name="rootGrid">
        <fl:FullScreenContainer x:Name="FSC">
            <fl:FlyleafHost x:Name="flyleafHost" Player="{Binding Player}">
                <TextBlock Text="Hello Flyleaf!"
                           Foreground="DarkOrange"
                           FontSize="50"/>
            </fl:FlyleafHost>
        </fl:FullScreenContainer>
    </Grid>
</Window>
```

```csharp
public sealed partial class MainWindow : Window
{
    public Player Player { get; set; }
    public Config Config { get; set; }
    public MainWindow()
    {
        Config = new Config();
        Config.Video.BackgroundColor = System.Windows.Media.Colors.DarkGray;
        Player = new Player(Config);
        InitializeComponent();
        rootGrid.DataContext = this;
        FSC.FullScreenEnter += (o, e) => flyleafHost.KFC.Focus(FocusState.Keyboard);
        FSC.FullScreenExit += (o, e) => Task.Run(() => {
            Thread.Sleep(10);
            Utils.UIInvoke(() => flyleafHost.KFC.Focus(FocusState.Keyboard));
        });
    }
}
```

--------------------------------

### Initialize Flyleaf Engine in WinUI 3 App

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Configures and starts the Flyleaf Engine upon application launch. It includes settings for FFmpeg path, logging levels (debug/release), and UI refresh intervals. Ensure FFmpeg is installed at the specified path.

```csharp
using FlyleafLib;
using Microsoft.UI.Xaml;

namespace FlyleafSample;

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        Engine.Start(new EngineConfig()
        {
            FFmpegPath          = @"C:\\Flyleaf\\FFmpeg",
            FFmpegDevices       = false,    // Prevents loading avdevice/avfilter dll files. Enable it only if you plan to use dshow/gdigrab etc.

            #if RELEASE
            FFmpegLogLevel      = Flyleaf.FFmpeg.LogLevel.Quiet,
            LogLevel            = LogLevel.Quiet,

            #else
            FFmpegLogLevel      = Flyleaf.FFmpeg.LogLevel.Warn,
            LogLevel            = LogLevel.Debug,
            LogOutput           = ":debug",
            //LogOutput         = ":console",
            //LogOutput         = @"C:\\Flyleaf\\Logs\\flyleaf.log",                
            #endif

            //PluginsPath       = @"C:\\Flyleaf\\Plugins",

            UIRefresh           = false,    // Required for Activity, BufferedDuration, Stats in combination with Config.Player.Stats = true
            UIRefreshInterval   = 250,      // How often (in ms) to notify the UI
            UICurTimePerSecond  = true,     // Whether to notify UI for CurTime only when it's second changed or by UIRefreshInterval
        });
    }
    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        m_window = new MainWindow();
        m_window.Activate();
    }

    private Window m_window;
}
```

--------------------------------

### Initialize Flyleaf Engine

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Configures and starts the Flyleaf engine in the application entry point. This includes setting FFmpeg paths, log levels, and UI refresh settings.

```csharp
using FlyleafLib;

namespace FlyleafSample
{
    internal static class Program
    {
        [STAThread]
        static void Main()
        {
            Engine.Start(new EngineConfig()
            {
                FFmpegPath          = @"C:\Flyleaf\FFmpeg",
                FFmpegDevices       = false,
                #if RELEASE
                FFmpegLogLevel      = Flyleaf.FFmpeg.LogLevel.Quiet,
                LogLevel            = LogLevel.Quiet,
                #else
                FFmpegLogLevel      = Flyleaf.FFmpeg.LogLevel.Warn,
                LogLevel            = LogLevel.Debug,
                LogOutput           = ":debug",
                #endif
                UIRefresh           = false,
                UIRefreshInterval   = 250,
                UICurTimePerSecond  = true,
            });

            ApplicationConfiguration.Initialize();
            Application.Run(new Form1());
        }
    }
}
```

--------------------------------

### FlyleafHost Control (WPF)

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Integration guide for the FlyleafHost DPI-aware rendering surface in WPF applications.

```APIDOC
## FlyleafHost Control (WPF)

### Description
FlyleafHost provides a rendering surface for WPF applications, supporting overlays and detached modes.

### Method
N/A (XAML Control)

### Parameters
- **Player** (Player) - Required - The Flyleaf Player instance.
- **AttachedDragMove** (string) - Optional - Drag move behavior.
- **KeepRatioOnResize** (bool) - Optional - Maintains aspect ratio on window resize.

### Request Example
<fl:FlyleafHost Player="{Binding Player}" KeepRatioOnResize="True" />

### Response
- **FlyleafHost** (UIElement) - The rendered video surface with optional overlay support.
```

--------------------------------

### GET /player/open/clipboard

Source: https://github.com/surgeonix/flyleaf/wiki/Player (Open)

Opens a media source directly from the system clipboard.

```APIDOC
## GET /player/open/clipboard

### Description
Retrieves a URL from the system clipboard and attempts to open it as a media source in the player.

### Method
GET

### Endpoint
/player/open/clipboard

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the clipboard content is being processed.
```

--------------------------------

### Setup Flyleaf Player and UI in WinUI 3 MainWindow

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Initializes the Flyleaf Player and its configuration within the MainWindow. It also sets up event handlers for full-screen mode to ensure proper keyboard focus management. The DataContext is set to allow binding UI elements to the player.

```csharp
using FlyleafLib;
using FlyleafLib.MediaPlayer;
using Microsoft.UI.Xaml;
using System.Threading.Tasks;
using System.Threading;

namespace FlyleafSample;

public sealed partial class MainWindow : Window
{
    public Player Player { get; set; }
    public Config Config { get; set; }

    public MainWindow()
    {
        Config = new Config();
        Config.Video.BackgroundColor = System.Windows.Media.Colors.DarkGray;

        Player = new Player(Config);

        InitializeComponent();
        rootGrid.DataContext = this;

        // Keyboard focus fix
        FSC.FullScreenEnter += (o, e) => flyleafHost.KFC.Focus(FocusState.Keyboard);
        FSC.FullScreenExit += (o, e) => Task.Run(() => 
            { Thread.Sleep(10); Utils.UIInvoke(() => flyleafHost.KFC.Focus(FocusState.Keyboard)); });
    }
}
```

--------------------------------

### Custom Plugin Development in C# for Flyleaf

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates how to create custom plugins for Flyleaf using C#. This includes examples for suggesting video and audio streams based on custom criteria, and defining plugin-specific options. Compiled plugin DLLs should be placed in the 'Plugins' directory.

```csharp
using FlyleafLib.MediaFramework.MediaStream;
using FlyleafLib.Plugins;
using System.Collections.ObjectModel;

/// <summary>
/// Custom Video Stream Suggester - selects highest resolution with best FPS
/// </summary>
public class CustomVideoStreamSuggester : PluginBase, ISuggestVideoStream
{
    // Higher priority takes precedence (default StreamSuggester has priority 0)
    public new int Priority { get; set; } = 1;

    public VideoStream SuggestVideo(ObservableCollection<VideoStream> streams)
    {
        return streams
            .OrderByDescending(s => s.Height)
            .ThenByDescending(s => s.FPS)
            .FirstOrDefault();
    }
}

/// <summary>
/// Custom Audio Stream Suggester - prefers specific language and codec
/// </summary>
public class CustomAudioStreamSuggester : PluginBase, ISuggestAudioStream
{
    public new int Priority { get; set; } = 1;

    public AudioStream SuggestAudio(ObservableCollection<AudioStream> streams,
                                     VideoStream videoStream)
    {
        // Prefer English AAC audio
        var preferred = streams
            .Where(s => s.Language?.ISO639_1 == "en")
            .Where(s => s.Codec?.Contains("aac") == true)
            .OrderByDescending(s => s.BitRate)
            .FirstOrDefault();

        return preferred ?? streams.FirstOrDefault();
    }
}

/// <summary>
/// Custom plugin options example
/// </summary>
public class MyPlugin : PluginBase
{
    public override Dictionary<string, string> GetDefaultOptions()
    {
        return new Dictionary<string, string>
        {
            { "ApiKey", "" },
            { "MaxResults", "10" },
            { "PreferHD", "true" }
        };
    }

    // Access options via: Config.Plugins["MyPlugin"]["ApiKey"]
}

// Place compiled plugin DLLs in the Plugins directory
// Structure: Plugins/MyPlugin/MyPlugin.dll
```

--------------------------------

### Initialize Flyleaf Engine in App.xaml.cs

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Configures and starts the Flyleaf engine during application startup. It sets paths for FFmpeg and defines logging levels based on build configuration.

```csharp
using FlyleafLib;
using System.Windows;

namespace FlyleafSample
{
    public partial class App : Application
    {
        protected override void OnStartup(StartupEventArgs e)
        {
            base.OnStartup(e);

            Engine.Start(new EngineConfig()
            {
                FFmpegPath = @"C:\Flyleaf\FFmpeg",
                FFmpegDevices = false,
                #if RELEASE
                FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Quiet,
                LogLevel = LogLevel.Quiet,
                #else
                FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Warn,
                LogLevel = LogLevel.Debug,
                LogOutput = ":debug",
                #endif
                UIRefresh = false,
                UIRefreshInterval = 250,
                UICurTimePerSecond = true
            });
        }
    }
}
```

--------------------------------

### Download Media Streams with Flyleaf Downloader in C#

Source: https://context7.com/surgeonix/flyleaf/llms.txt

This C# code demonstrates how to use the Flyleaf Downloader class to download media streams to local files. It covers initializing the engine, configuring downloader settings such as buffer duration and preferred video resolution, and setting up event handlers for download progress and completion. The example also shows how to open a media stream, list available video and audio streams, and initiate the download process.

```csharp
using FlyleafLib;
using FlyleafLib.MediaFramework.MediaContext;

// Initialize Engine
Engine.Start(new EngineConfig()
{
    FFmpegPath = ":FFmpeg",
    PluginsPath = ":Plugins"
});

// Configure downloader
Config config = new Config();
config.Demuxer.FormatOptToUnderlying = true;  // Pass query params for HLS sessions
config.Demuxer.BufferDuration = 60 * 1000 * 10000;  // 60 seconds buffer
config.Demuxer.ReadTimeout = 60 * 1000 * 10000;     // 60 seconds timeout
config.Video.MaxVerticalResolutionCustom = 1080;    // Prefer 1080p streams

// Create downloader
Downloader downloader = new Downloader(config);

// Event handlers
downloader.PropertyChanged += (s, e) =>
{
    switch (e.PropertyName)
    {
        case "CurTime":
        case "Duration":
            var cur = TimeSpan.FromTicks(downloader.CurTime);
            var dur = TimeSpan.FromTicks(downloader.Duration);
            Console.WriteLine($"Progress: {cur:hh\:mm\:ss} / {dur:hh\:mm\:ss}");
            break;
        case "DownloadPercentage":
            Console.WriteLine($"Downloaded: {downloader.DownloadPercentage:F1}%");
            break;
    }
};

downloader.DownloadCompleted += (s, success) =>
{
    if (success)
        Console.WriteLine(downloader.DownloadPercentage == 100
            ? "Download completed!"
            : "Download completed (partial)");
    else
        Console.WriteLine("Download failed!");
};

// Open media
string error = downloader.Open("https://example.com/video.mp4");
if (error != null)
{
    Console.WriteLine($"Open error: {error}");
    return;
}

// List available streams
Console.WriteLine("Video Streams:");
foreach (var stream in downloader.DecCtx.VideoDemuxer.VideoStreams)
    Console.WriteLine($"  {stream.Width}x{stream.Height} @ {stream.FPS}fps ({stream.Codec})");

Console.WriteLine("Audio Streams:");
foreach (var stream in downloader.DecCtx.VideoDemuxer.AudioStreams)
    Console.WriteLine($"  {stream.Codec} {stream.SampleRate}Hz {stream.Channels}ch");

// Start download
string filename = @"C:\Downloads\video.mp4";
downloader.Download(ref filename, useRecommendedExtension: true);

// To stop download
// downloader.Dispose();
```

--------------------------------

### Configuring Key and Mouse Bindings in Flyleaf

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Shows how to customize keyboard shortcuts and mouse bindings for Flyleaf player control. It includes examples of default bindings and how to add custom actions, such as taking a snapshot with a specific key press.

```csharp
using FlyleafLib;
using FlyleafLib.MediaPlayer;

Config config = new Config();

// Default key bindings (can be customized)
// Playback
// O or Drag & Drop    - Open
// Ctrl + C/V          - Copy/Paste URL
// P or Space          - Toggle Play/Pause
// Ctrl + Q            - Stop
// Left/Right          - Seek Backward/Forward
// Ctrl + Left/Right   - Seek Backward2/Forward2
// -/+/0               - Speed Down/Up/Reset
// Backspace           - Toggle Reverse Playback
// F or Double-click   - Toggle Fullscreen
// Escape              - Exit Fullscreen

// Audio
// Shift + A           - Toggle Audio
// Up/Down             - Volume Up/Down
// M                   - Toggle Mute
// [/]                 - Audio Delay +/-
// Ctrl + [/]          - Audio Delay2 +/-

// Video
// Shift + V           - Toggle Video
// Ctrl + H            - Toggle Video Acceleration
// Ctrl + R            - Toggle Recording
// R                   - Toggle Keep/Fill Ratio
// Ctrl + T            - Take Snapshot
// Shift + Left/Right  - Previous/Next Frame
// Ctrl + +/-          - Zoom In/Out
// Ctrl + Drag         - Pan
// Shift + MouseWheel  - Rotate

// Subtitles
// Shift + S           - Toggle Subtitles
// ;/'                 - Subtitles Delay +/-
// Ctrl + ;/'          - Subtitles Delay2 +/-

// Custom key binding
config.Player.KeyBindings.Enabled = true;
config.Player.KeyBindings.FlyleafHostEnabled = true;

// Add custom action
Player player = new Player(config);
player.Host?.KeyDown += (s, e) =>
{
    if (e.Key == System.Windows.Input.Key.F5)
    {
        player.TakeSnapshotToFile();
        e.Handled = true;
    }
};

```

--------------------------------

### WPF FlyleafHost with Style Template

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

This WPF example demonstrates how to apply a style template to the FlyleafHost control. The 'OverlayTemplate' defined within the style is automatically transferred to the Overlay Window, allowing for customized visual appearance and behavior of the overlay content. This requires the 'FlyleafLib' assembly and 'FlyleafLib.Controls.WPF' namespace.

```xml
<Grid>
    <Grid.Resources>
        <ResourceDictionary>
            <Style TargetType="{x:Type fl:FlyleafHost}" BasedOn="{StaticResource {x:Type fl:FlyleafHost}}">
                <Setter Property="Width" Value="200"/>

```

--------------------------------

### General Status Properties

Source: https://github.com/surgeonix/flyleaf/wiki/Engine

Indicates the status of plugins, players, and whether the system has started.

```APIDOC
## General Status Properties

### Description
Provides status indicators for plugins, players, and the overall started state of the application.

### Properties
- **Plugins** (object) - Status related to plugins.
- **Players** (object) - Status related to media players.
- **Started** (boolean) - Indicates if the application has started.
```

--------------------------------

### WPF FlyleafHost with Detached and Overlay Content

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Illustrates the implementation of FlyleafHost in WPF, which involves creating separate 'Surface Window' and optionally 'Overlay Window' due to WPF's rendering limitations. This example shows how to host detached content within the FlyleafHost and define overlay content that appears above the rendering surface. The 'FlyleafLib' assembly and 'FlyleafLib.Controls.WPF' namespace are required.

```xml
<fl:FlyleafHost Width="200" Height="120" Player="{Binding Player}">

    <fl:FlyleafHost.DetachedContent>
    
        <!-- Detached Content Here -->
        <Viewbox>
            <TextBlock Text="Hello Flyleaf Host!" Foreground="DarkRed"/>
        </Viewbox>
        
    </fl:FlyleafHost.DetachedContent>
    
    <!-- Overlay Content Here -->
    <Viewbox>
        <TextBlock Text="Hello Flyleaf Overlay!" Foreground="DarkRed"/>
    </Viewbox>

</fl:FlyleafHost>
```

--------------------------------

### Manual Stream Selection Workflow

Source: https://github.com/surgeonix/flyleaf/wiki/Player (Open)

Shows how to disable default automatic selection to manually configure playlist items, video streams, audio streams, and subtitles before starting playback.

```csharp
player.Open("youtube_url", false, false, false, false);
player.Open(player.Playlist.Items[0], false, false, false);
player.Open(player.Video.Streams[0], false, false);
player.Open(player.Audio.Streams[0], false, false);
player.Open("path/to/subtitles.srt");
player.Play();
```

--------------------------------

### Control Playback with Flyleaf Player API

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Provides examples of controlling media playback using the Flyleaf Player API. Includes methods for play, pause, stop, various seeking techniques (absolute, relative, accurate), frame stepping, playback speed adjustment, reverse playback, and looping.

```csharp
using FlyleafLib.MediaPlayer;

Player player = new Player();
player.OpenAsync(@"C:\\Videos\\sample.mp4");

// Wait for open to complete
player.OpenCompleted += (s, e) =>
{
    if (!e.Success) return;

    // Basic playback control
    player.Play();
    player.Pause();
    player.TogglePlayPause();
    player.Stop();

    // Seeking (milliseconds)
    player.Seek(30000);  // Seek to 30 seconds
    player.Seek(60000, forward: true);  // Forward seek to nearest keyframe
    player.SeekAccurate(45000);  // Accurate seek to exact frame

    // Relative seeking (uses config offsets)
    player.SeekBackward();   // Config.Player.SeekOffset (default 5 sec)
    player.SeekForward();
    player.SeekBackward2();  // Config.Player.SeekOffset2 (default 15 sec)
    player.SeekForward2();

    // Seek to specific positions
    player.SeekToStart();
    player.SeekToEnd();

    // Seek to chapter (if available)
    if (player.Chapters?.Count > 0)
        player.SeekToChapter(player.Chapters[0]);

    // Frame stepping
    player.ShowFrameNext();
    player.ShowFramePrev();
    player.ShowFrame(100);  // Show frame at index 100

    // Playback speed (0.125x to 16x)
    player.Speed = 2.0;  // 2x speed
    player.SpeedUp();    // Increase by SpeedOffset
    player.SpeedDown();  // Decrease by SpeedOffset

    // Reverse playback
    player.ReversePlayback = true;
    player.ToggleReversePlayback();

    // Loop playback
    player.LoopPlayback = true;

    // Flush buffer (useful for live streams to reduce latency)
    player.Flush();
};

// Seek completed event
player.SeekCompleted += (s, ms) =>
{
    if (ms >= 0)
        Console.WriteLine($"Seek completed to {ms}ms");
    else
        Console.WriteLine("Seek failed");
};

// Playback stopped event
player.PlaybackStopped += (s, e) =>
{
    if (e.Success)
        Console.WriteLine("Playback ended normally");
    else
        Console.WriteLine($"Playback stopped with error: {e.Error}");
};
```

--------------------------------

### Integrate Flyleaf Player Host in WinUI 3 XAML

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Defines the main window layout using XAML, embedding the Flyleaf player components. It uses `FullScreenContainer` and `FlyleafHost` to display video content and includes a fallback TextBlock for initial setup or error states. The `Player` property is bound to the `FlyleafHost`.

```xml
<Window
    x:Class="FlyleafSample.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:FlyleafSample"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:fl="using:FlyleafLib.Controls.WinUI"
    mc:Ignorable="d">

    <Grid x:Name="rootGrid">
        <fl:FullScreenContainer x:Name="FSC">
            <fl:FlyleafHost x:Name="flyleafHost" Player="{Binding Player}">
                <TextBlock Text="Hello Flyleaf!" Foreground="DarkOrange" HorizontalAlignment="Center" VerticalAlignment="Center" FontSize="50"/>
            </fl:FlyleafHost>
        </fl:FullScreenContainer>
    </Grid>
</Window>
```

--------------------------------

### Configure and Create Flyleaf Player

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates how to instantiate a Player object with custom configuration settings. This includes tuning demuxer buffers, video acceleration, audio volume, and subtitle language preferences.

```csharp
using FlyleafLib;
using FlyleafLib.MediaPlayer;

Config config = new Config();
config.Player.AutoPlay = true;
config.Player.SeekAccurate = false;
config.Player.MinBufferDuration = 500 * 10000;
config.Demuxer.BufferDuration = 30 * 1000 * 10000;
config.Video.Enabled = true;
config.Video.VideoAcceleration = true;
config.Audio.Enabled = true;
config.Audio.VolumeMax = 150;
config.Subtitles.Enabled = true;

Player player = new Player(config);
Console.WriteLine($"Player ID: {player.PlayerId}");
```

--------------------------------

### Record Media and Capture Snapshots in C#

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Shows how to configure recording directories, start/stop recording sessions, and capture video frames as files or bitmap objects.

```csharp
using FlyleafLib.MediaPlayer;

Player player = new Player();
player.Config.Player.FolderRecordings = @"C:\Recordings";
player.Config.Player.FolderSnapshots = @"C:\Snapshots";
player.Config.Player.SnapshotFormat = "png";  // bmp, png, jpg

player.OpenAsync(@"C:\Videos\sample.mp4");

// Recording
player.OpenCompleted += (s, e) =>
{
    if (!e.Success) return;

    player.Play();

    // Start recording (auto filename)
    player.StartRecording();

    // Start recording (custom filename)
    string filename = @"C:\Recordings\myrecording.mp4";
    player.StartRecording(ref filename, useRecommendedExtension: true);

    // Check recording status
    Console.WriteLine($"Is Recording: {player.IsRecording}");

    // Stop recording
    player.StopRecording();

    // Toggle recording
    player.ToggleRecording();
};

// Recording completed event
player.decoder.RecordingCompleted += (s, e) =>
{
    Console.WriteLine("Recording completed");
};

// Snapshots
player.OpenCompleted += (s, e) =>
{
    if (!e.Success) return;

    // Snapshot to file (auto filename)
    player.TakeSnapshotToFile();

    // Snapshot to specific file
    player.TakeSnapshotToFile(@"C:\Snapshots\frame.png");

    // Snapshot with custom size (maintains aspect ratio if one dimension is 0)
    player.TakeSnapshotToFile(@"C:\Snapshots\thumb.jpg", width: 320, height: 0);

    // Snapshot to Bitmap object
    System.Drawing.Bitmap bitmap = player.TakeSnapshotToBitmap();
    bitmap?.Save(@"C:\Snapshots\bitmap.bmp");
    bitmap?.Dispose();

    // Snapshot to BitmapSource (WPF)
    var bitmapSource = player.TakeSnapshotToBitmapSource(width: 640, height: 360);
};
```

--------------------------------

### Basic Media Opening

Source: https://github.com/surgeonix/flyleaf/wiki/Player (Open)

Demonstrates the simplest way to open a media file using the asynchronous OpenAsync method with default settings.

```csharp
player.OpenAsync("path/to/video.mp4");
```

--------------------------------

### Initialize Flyleaf Engine and Host in WinForms

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Shows how to initialize the Flyleaf engine in the Program entry point and bind the Player to a FlyleafHost control in a WinForms Form. Includes handling of property change notifications for UI updates.

```csharp
static class Program
{
    [STAThread]
    static void Main()
    {
        Engine.Start(new EngineConfig()
        {
            FFmpegPath = ":FFmpeg",
            PluginsPath = ":Plugins",
            #if DEBUG
            LogOutput = ":debug",
            LogLevel = LogLevel.Debug,
            FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Warn,
            #endif
            UIRefresh = false
        });
        ApplicationConfiguration.Initialize();
        Application.Run(new Form1());
    }
}
```

```csharp
public partial class Form1 : Form
{
    public Player Player { get; set; }
    public Config Config { get; set; }
    public Form1()
    {
        Config = new Config();
        Config.Video.BackgroundColor = System.Windows.Media.Colors.DarkGray;
        Player = new Player(Config);
        InitializeComponent();
        flyleafHost1.Player = Player;
        Player.PropertyChanged += (s, e) => {
            switch (e.PropertyName) {
                case "Status": UpdateUI(); break;
                case "CurTime": lblTime.Text = TimeSpan.FromTicks(Player.CurTime).ToString(@"hh\:mm\:ss"); break;
            }
        };
    }
    void UpdateUI() { btnPlay.Text = Player.IsPlaying ? "Pause" : "Play"; }
}
```

--------------------------------

### Open Media Files with Flyleaf Player

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates how to open local files, URLs, streams, and custom IO streams using Flyleaf's OpenAsync and Open methods. It covers event handling for open operations and various opening scenarios including external subtitles and file dialogs.

```csharp
using FlyleafLib.MediaPlayer;

Player player = new Player();

// Event handlers for open operations
player.Opening += (s, e) => Console.WriteLine($"Opening: {e.Url}");

player.OpenCompleted += (s, e) =>
{
    if (e.Success)
    {
        Console.WriteLine($"Opened successfully!");
        Console.WriteLine($"Duration: {TimeSpan.FromTicks(player.Duration)}");
        Console.WriteLine($"Is Live: {player.IsLive}");
        Console.WriteLine($"Video: {player.Video.Width}x{player.Video.Height} @ {player.Video.FPS}fps");
        Console.WriteLine($"Audio: {player.Audio.Channels}ch {player.Audio.SampleRate}Hz");
    }
    else
        Console.WriteLine($"Open failed: {e.Error}");
};

// Non-blocking open (recommended for UI applications)
player.OpenAsync(@"C:\\Videos\\sample.mp4");

// Or open a URL (supports http, https, rtsp, hls, etc.)
player.OpenAsync("https://example.com/video.m3u8");

// Synchronous open (blocking)
var result = player.Open(@"C:\\Videos\\sample.mp4");
if (result.Success)
    player.Play();

// Open with manual stream selection (no defaults)
player.OpenAsync("https://youtube.com/watch?v=xxx",
    defaultPlaylistItem: false,
    defaultVideo: false,
    defaultAudio: false,
    defaultSubtitles: false);

// Then manually select streams from player.Playlist.Items, player.Video.Streams, etc.

// Open a custom IO stream
using FileStream fs = new FileStream(@"C:\\Videos\\sample.mp4", FileMode.Open);
player.Open(fs);

// Open external subtitles
player.Open(@"C:\\Videos\\sample.srt", forceSubtitles: true);

// Open from clipboard
player.OpenFromClipboard();

// Open file dialog
player.OpenFromFileDialog();
```

--------------------------------

### Integrate Flyleaf Player in WinForms

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Demonstrates how to instantiate the Flyleaf Player and attach it to a FlyleafHost control within a Form. It configures basic video settings like background color.

```csharp
using FlyleafLib;
using FlyleafLib.MediaPlayer;

namespace FlyleafSample
{
    public partial class Form1 : Form
    {
        public Player Player { get; set; }
        public Config Config { get; set; }

        public Form1()
        {
            Config = new Config();
            Config.Video.BackgroundColor = System.Windows.Media.Colors.DarkGray;

            Player = new Player(Config);

            InitializeComponent();

            flyleafHost1.Player = Player;
        }
    }
}
```

--------------------------------

### Engine Initialization

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Configures the global Flyleaf engine settings, including FFmpeg paths and logging levels, during application startup.

```APIDOC
## Engine.Start(EngineConfig config)

### Description
Initializes the global Flyleaf engine. This must be called before any player instances are created.

### Method
Static Method

### Parameters
#### Request Body
- **FFmpegPath** (string) - Required - Absolute path to the FFmpeg binaries.
- **FFmpegDevices** (bool) - Optional - Whether to load avdevice/avfilter DLLs.
- **FFmpegLogLevel** (Enum) - Optional - Sets the verbosity of FFmpeg logs.
- **LogLevel** (Enum) - Optional - Sets the internal Flyleaf log level.
- **UIRefresh** (bool) - Optional - Enables UI refresh notifications for stats and duration.

### Request Example
{
  "FFmpegPath": "C:\\Flyleaf\\FFmpeg",
  "FFmpegDevices": false,
  "LogLevel": "Debug"
}
```

--------------------------------

### Manage Subtitle Display and Configuration in C#

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates how to enable subtitles, adjust timing delays, load external subtitle files, and configure language preferences using the FlyleafLib.MediaPlayer namespace.

```csharp
using FlyleafLib.MediaPlayer;

Player player = new Player();

// Enable/disable subtitles
player.Config.Subtitles.Enabled = true;
player.Config.Subtitles.Toggle();

// Subtitle delay (ticks)
player.Config.Subtitles.Delay = 200 * 10000;  // 200ms delay
player.Config.Subtitles.DelayAdd();
player.Config.Subtitles.DelayRemove();

// Open external subtitle file
player.Open(@"C:\Videos\subtitle.srt", forceSubtitles: true);

// Subtitle stream selection
foreach (var stream in player.Subtitles.Streams)
{
    Console.WriteLine($"Subtitle {stream.StreamIndex}: {stream.Language} - {stream.Codec}");
}
if (player.Subtitles.Streams.Count > 1)
    player.Open(player.Subtitles.Streams[1]);

// Current subtitle text (for custom rendering)
Console.WriteLine($"Current text: {player.Subtitles.SubsText}");

// Subtitle search settings
player.Config.Subtitles.SearchLocal = true;  // Search local files
player.Config.Subtitles.SearchOnline = false;  // OpenSubtitles.org (requires plugin)
player.Config.Subtitles.SearchLocalOnInputType = new List<InputType>
{
    InputType.File,
    InputType.UNC,
    InputType.Torrent
};

// Language preference
player.Config.Subtitles.Languages = new List<Language>
{
    Language.Get("eng"),
    Language.Get("spa")
};

// Subtitle information
if (player.Subtitles.IsOpened)
{
    Console.WriteLine($"Codec: {player.Subtitles.Codec}");
}
```

--------------------------------

### Implement FlyleafHost in WPF Applications

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Provides the XAML structure for the FlyleafHost control and the corresponding C# initialization logic for the WPF window.

```xml
<!-- MainWindow.xaml -->
<Window xmlns:fl="clr-namespace:FlyleafLib.Controls.WPF;assembly=FlyleafLib">
    <Grid>
        <fl:FlyleafHost
            Player="{Binding Player}"
            AttachedDragMove="Both"
            KeyBindings="Both"
            AttachedResize="Both"
            KeepRatioOnResize="True"
            OpenOnDrop="True">

            <!-- Overlay content (rendered above video) -->
            <Grid>
                <TextBlock Text="Overlay Content"
                           Foreground="White"
                           HorizontalAlignment="Center"
                           VerticalAlignment="Bottom"/>
            </Grid>

            <!-- Detached content (shown when detached) -->
            <fl:FlyleafHost.DetachedContent>
                <TextBlock Text="Detached Mode" Foreground="Red"/>
            </fl:FlyleafHost.DetachedContent>

        </fl:FlyleafHost>
    </Grid>
</Window>
```

```csharp
// MainWindow.xaml.cs
using FlyleafLib;
using FlyleafLib.MediaPlayer;

public partial class MainWindow : Window
{
    public Player Player { get; set; }
    public Config Config { get; set; }

    public MainWindow()
    {
        // Initialize Engine
        Engine.Start(new EngineConfig()
        {
            FFmpegPath = ":FFmpeg",
            PluginsPath = ":Plugins"
        });

        Config = new Config();
        Config.Video.BackgroundColor = Colors.DarkGray;

        Player = new Player(Config);

        InitializeComponent();
        DataContext = this;
    }
}
```

--------------------------------

### Initialize Standalone FlyleafHost in C#

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Programmatically initializes a FlyleafHost instance in the code-behind, setting up key bindings and detached window behavior. Requires Engine.Start() to be called during application startup.

```csharp
public FlyleafHost FlyleafHost { get; set; }
public Player Player { get; set; } = new Player();

public MainWindow() {
    FlyleafHost = new FlyleafHost(this) {
        KeyBindings = AvailableWindows.Both,
        DetachedResize = AvailableWindows.Both,
        IsAttached = false,
        Player = Player
    };
    InitializeComponent();
    DataContext = this;
}
```

--------------------------------

### Player Instantiation

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Creates and binds a media player instance to a FlyleafHost control within a WinForms Form.

```APIDOC
## Player Constructor

### Description
Instantiates a new Player object with specific configuration and attaches it to the UI host.

### Method
Constructor

### Parameters
#### Path Parameters
- **Config** (Object) - Required - Configuration object defining video properties like background color.

### Request Example
{
  "Config": {
    "Video": { "BackgroundColor": "DarkGray" }
  }
}

### Response
#### Success Response (200)
- **Player** (Object) - Returns a fully initialized Player instance ready to be assigned to a FlyleafHost.
```

--------------------------------

### Implement Custom Overlay Window in WPF

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Demonstrates how to define a custom OverlayWindow in XAML resources and bind it to the FlyleafHost instance. Note that this configuration may not render in design mode.

```xml
<Window.Resources>
    <local:OverlayWindow x:Key="OverlayWindow"/>
</Window.Resources>
<Grid>
    <fl:FlyleafHost Player="{Binding Player}" Overlay="{StaticResource OverlayWindow}"/>
</Grid>
```

--------------------------------

### Initialize FlyleafHost in WinForms

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Basic initialization for WinForms by assigning a player instance to the FlyleafHost control. Note that advanced features like overlays are currently limited in the WinForms implementation.

```csharp
Player player = new Player();
flyleafControl1.Player = player;
```

--------------------------------

### Initialize Flyleaf Engine

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Configures the global Flyleaf engine settings, including FFmpeg paths, logging levels, and plugin directories. This must be called on the UI thread during application startup before any player instances are created.

```csharp
using FlyleafLib;

Engine.Start(new EngineConfig()
{
    FFmpegPath = @"C:\Flyleaf\FFmpeg",
    FFmpegDevices = false,
    FFmpegLogLevel = Flyleaf.FFmpeg.LogLevel.Warn,
    LogLevel = LogLevel.Debug,
    LogOutput = ":debug",
    PluginsPath = ":Plugins",
    UIRefresh = true,
    UIRefreshInterval = 250,
    UICurTimePerSecond = true,
    KeepDisplayActive = true
});

if (Engine.IsLoaded)
{
    Console.WriteLine($"FFmpeg Version: {Engine.FFmpeg.Version}");
    Console.WriteLine($"GPU Adapters: {string.Join(", ", Engine.Video.GPUAdapters)}");
    Console.WriteLine($"Audio Devices: {string.Join(", ", Engine.Audio.Devices)}");
}
```

--------------------------------

### Custom Plugin Development

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Learn how to implement custom stream suggesters and plugin configurations to extend Flyleaf's media handling capabilities.

```APIDOC
## Custom Plugin Development

### Description
Extend Flyleaf by implementing `ISuggestVideoStream` or `ISuggestAudioStream` interfaces. Plugins allow for custom logic in selecting media streams based on resolution, codec, or language preferences.

### Implementation
- Create a class inheriting from `PluginBase`.
- Implement the required interface (`ISuggestVideoStream` or `ISuggestAudioStream`).
- Override `GetDefaultOptions` to define plugin-specific configuration settings.

### Deployment
Place the compiled DLL in the `Plugins/PluginName/` directory.

### Example
```csharp
public class CustomVideoStreamSuggester : PluginBase, ISuggestVideoStream
{
    public int Priority { get; set; } = 1;
    public VideoStream SuggestVideo(ObservableCollection<VideoStream> streams) => streams.OrderByDescending(s => s.Height).FirstOrDefault();
}
```
```

--------------------------------

### POST /player/open

Source: https://github.com/surgeonix/flyleaf/wiki/Player (Open)

Opens a media source using the Flyleaf player, allowing for either automatic or manual stream selection.

```APIDOC
## POST /player/open

### Description
Opens a media source (URL or Stream) in the player. Supports blocking (Open) and non-blocking (OpenAsync) execution, with optional flags to disable default stream selection.

### Method
POST

### Endpoint
/player/open

### Parameters
#### Request Body
- **url** (string) - Required - The path to the video file or stream URL.
- **defaultPlaylistItem** (boolean) - Optional - Whether to automatically select the playlist item.
- **defaultVideo** (boolean) - Optional - Whether to automatically select the video stream.
- **defaultAudio** (boolean) - Optional - Whether to automatically select the audio stream.
- **defaultSubtitles** (boolean) - Optional - Whether to automatically select the subtitle stream.

### Request Example
{
  "url": "https://example.com/video.mp4",
  "defaultPlaylistItem": true,
  "defaultVideo": true,
  "defaultAudio": true,
  "defaultSubtitles": true
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation has been initiated or completed.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Keyboard and Mouse Bindings

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Configure and customize input bindings for media player control in Flyleaf.

```APIDOC
## Player Input Bindings

### Description
Flyleaf supports a robust set of default keyboard and mouse shortcuts. Developers can enable or override these bindings via the `Config` object.

### Configuration
- `config.Player.KeyBindings.Enabled`: Set to true to activate standard shortcuts.
- `config.Player.KeyBindings.FlyleafHostEnabled`: Enables host-level key event handling.

### Custom Action Example
```csharp
player.Host?.KeyDown += (s, e) =>
{
    if (e.Key == System.Windows.Input.Key.F5)
    {
        player.TakeSnapshotToFile();
        e.Handled = true;
    }
};
```
```

--------------------------------

### Configure Flyleaf Player in MainWindow.xaml.cs

Source: https://github.com/surgeonix/flyleaf/wiki/Home

Instantiates the Flyleaf Player and Config objects within the MainWindow. This binds the player instance to the UI data context.

```csharp
using System.Windows;
using System.Windows.Media;
using FlyleafLib;
using FlyleafLib.MediaPlayer;

namespace FlyleafSample
{
    public partial class MainWindow : Window
    {
        public Player Player { get; set; }
        public Config Config { get; set; }

        public MainWindow()
        {
            Config = new Config();
            Config.Video.BackgroundColor = Colors.DarkGray;
            Player = new Player(Config);
            InitializeComponent();
            DataContext = this;
        }
    }
}
```

--------------------------------

### Configure FlyleafHost with XAML Styles and Overlays

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Defines a ResourceDictionary style for FlyleafHost, including custom detached content and overlay templates. This approach allows for styling the player UI directly within XAML.

```xml
<Setter Property="Height" Value="120"/>
<Setter Property="AttachedDragMove" Value="Surface"/>
<Setter Property="DetachedContent">
    <Setter.Value>
        <Viewbox>
            <TextBlock Text="Hello Flyleaf Host!" Foreground="DarkRed"/>
        </Viewbox>
    </Setter.Value>
</Setter>
<Setter Property="OverlayTemplate">
    <Setter.Value>
        <ControlTemplate>
            <Viewbox>
                <TextBlock Text="Hello Flyleaf Overlay!" Foreground="DarkRed"/>
            </Viewbox>
        </ControlTemplate>
    </Setter.Value>
</Setter>
<fl:FlyleafHost Player="{Binding Player}"/>
```

--------------------------------

### Manage Playback Sessions

Source: https://context7.com/surgeonix/flyleaf/llms.txt

Demonstrates how to capture the current playback state into a Session object and restore it later. This includes handling stream selections, playback position, and synchronization settings.

```csharp
Player player = new Player();
player.OpenCompleted += (s, e) => {
    if (!e.Success) return;
    player.Play();
    Session session = player.GetSession();
    Console.WriteLine($"Position: {TimeSpan.FromTicks(session.CurTime)}");
};

// Serialize and Restore
string json = System.Text.Json.JsonSerializer.Serialize(savedSession);
Session restored = System.Text.Json.JsonSerializer.Deserialize<Session>(json);
player.Open(restored);
```

--------------------------------

### WinUI 3 FlyleafHost Integration

Source: https://github.com/surgeonix/flyleaf/wiki/FlyleafHost

Demonstrates how to integrate FlyleafHost as a standard control within a WinUI 3 application. This approach allows direct composition with the WinUI SwapChainPanel, enabling the application to use FlyleafHost like any other UI element. It requires the 'FlyleafLib.Controls.WinUI' namespace.

```xml
<fl:FlyleafHost Player="{Binding Player}">
    <TextBlock Text="Hello Flyleaf Host!" Foreground="DarkRed" HorizontalAlignment="Center" VerticalAlignment="Center" FontSize="50"/>
</fl:FlyleafHost>
```

```xml
<fl:FullScreenContainer x:Name="FSC">
  <fl:FlyleafHost Player="{Binding Player}">
      <TextBlock Text="Hello Flyleaf Host!" Foreground="DarkRed" HorizontalAlignment="Center" VerticalAlignment="Center" FontSize="50"/>
  </fl:FlyleafHost>
</fl:FullScreenContainer>
```

--------------------------------

### Implement Custom Video Stream Suggester in C#

Source: https://github.com/surgeonix/flyleaf/wiki/Advanced

This snippet demonstrates how to create a custom video stream suggester by inheriting from PluginBase and implementing the ISuggestVideoStream interface. It provides logic to select a video stream based on the highest resolution and frame rate.

```csharp
using FlyleafLib.MediaFramework.MediaStream;
using FlyleafLib.Plugins;
using System.Collections.Generic;
using System.Linq;

public class CustomVideoStreamSuggester : PluginBase, ISuggestVideoStream
{
	public new int Priority { get; set; } = 1;

	public VideoStream SuggestVideo(ObservableCollection<VideoStream> streams)
	{
		return streams.OrderByDescending(stream => stream.Height).ThenByDescending(stream => stream.FPS).FirstOrDefault();
	}
}
```

--------------------------------

### Configure Flyleaf Video Settings and Viewport

Source: https://context7.com/surgeonix/flyleaf/llms.txt

This C# snippet demonstrates how to configure various video rendering and viewport settings for the Flyleaf player. It includes enabling/disabling video, selecting video processors, hardware acceleration, aspect ratio adjustments, pan, zoom, rotation, flipping, cropping, video filters, HDR to SDR conversion, deinterlacing, super resolution, and background color.

```csharp
using FlyleafLib.MediaPlayer;

Player player = new Player();

// Enable/disable video
player.Config.Video.Enabled = true;
player.Config.Video.Toggle();

// Video processor selection
player.Config.Video.VideoProcessor = VideoProcessors.Auto;  // Auto, FlyleafVP, D3D11

// Hardware acceleration
player.Config.Video.VideoAcceleration = true;
player.Config.Video.ToggleVideoAcceleration();

// Aspect ratio
player.Config.Video.AspectRatio = AspectRatio.Keep;  // Keep, Fill, Custom
player.Config.Video.CustomAspectRatio = new AspectRatio(16, 9);
player.Config.Video.ToggleKeepRatio();

// Pan (offset in pixels)
player.Config.Video.PanXOffset = 100;
player.Config.Video.PanYOffset = -50;

// Zoom (1.0 = 100%, 2.0 = 200%)
player.Config.Video.Zoom = 1.5;
player.ZoomIn();
player.ZoomOut();

// Rotation (degrees)
player.Config.Video.Rotation = 90;
player.RotateLeft();  // -90 degrees
player.RotateRight(); // +90 degrees

// Flip
player.Config.Video.HFlip = true;  // Horizontal flip
player.Config.Video.VFlip = true;  // Vertical flip

// Cropping (pixels from each edge)
player.Config.Video.Crop = new Thickness(10, 20, 10, 20);  // Left, Top, Right, Bottom

// Video filters (FlyleafVP)
player.Config.Video.Brightness = 0;  // -100 to 100
player.Config.Video.Contrast = 0;    // -100 to 100
player.Config.Video.Hue = 0;         // -180 to 180
player.Config.Video.Saturation = 0;  // -100 to 100

// HDR to SDR conversion (FlyleafVP only)
player.Config.Video.HDRtoSDRMethod = HDRtoSDRMethod.Hable;  // Aces, Hable, Reinhard
player.Config.Video.SDRDisplayNitsCustom = 200;  // Display brightness

// Deinterlace (D3D11VP only)
player.Config.Video.DeInterlace = DeInterlace.Auto;  // Auto, On, Off
player.Config.Video.DoubleRate = true;  // Bob deinterlacing

// Super Resolution (Nvidia/Intel, D3D11VP only)
player.Config.Video.SuperResolution = true;

// Background color
player.Config.Video.BackgroundColor = System.Windows.Media.Colors.Black;

// Reset all viewport settings
player.ResetAll();  // Resets zoom, pan, rotation, speed, delays
player.Config.Video.ResetViewport();
```