feat: add automatic resource lifecycle management

Add ref counting for encoders so they auto-dispose when no outputs reference
them. Centralize source/output tracking in Obs class with AutoDispose flag.
Track audio encoders by track index to properly detach when replaced.
Add GameCapture hook state tracking with Hooked/Unhooked events.
Improve Scene disposal to clean up channel assignments and owned items.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Segergren

src/ObsKit.NET/Encoders/AudioEncoder.cs

@@ -6,9 +6,12 @@ namespace ObsKit.NET.Encoders;
 
 /// <summary>
 /// Represents an OBS audio encoder (obs_encoder_t).
+/// Supports ref counting for automatic disposal when no outputs reference it.
 /// </summary>
 public sealed class AudioEncoder : ObsObject
 {
+    private int _refCount = 0;
+    private readonly object _refLock = new();
     /// <summary>Known audio encoder type IDs.</summary>
     public static class Types
     {
@@ -156,6 +159,53 @@ internal void SetAudio(AudioHandle audio)
         ObsEncoder.obs_encoder_set_audio(Handle, audio);
     }
 
+    /// <summary>
+    /// Attaches this encoder to an output, incrementing the ref count.
+    /// </summary>
+    internal void Attach()
+    {
+        lock (_refLock)
+        {
+            _refCount++;
+        }
+    }
+
+    /// <summary>
+    /// Detaches this encoder from an output, decrementing the ref count.
+    /// When ref count reaches 0 and AutoDispose is enabled, the encoder is disposed.
+    /// </summary>
+    internal void Detach()
+    {
+        bool shouldDispose = false;
+        lock (_refLock)
+        {
+            _refCount--;
+            if (_refCount <= 0 && Obs.AutoDispose)
+            {
+                shouldDispose = true;
+            }
+        }
+
+        if (shouldDispose)
+        {
+            Dispose();
+        }
+    }
+
+    /// <summary>
+    /// Gets the current reference count (number of outputs using this encoder).
+    /// </summary>
+    public int RefCount
+    {
+        get
+        {
+            lock (_refLock)
+            {
+                return _refCount;
+            }
+        }
+    }
+
     /// <inheritdoc/>
     protected override void ReleaseHandle(nint handle)
     {

src/ObsKit.NET/Encoders/VideoEncoder.cs

@@ -21,9 +21,12 @@ public enum RateControl
 
 /// <summary>
 /// Represents an OBS video encoder (obs_encoder_t).
+/// Supports ref counting for automatic disposal when no outputs reference it.
 /// </summary>
 public sealed class VideoEncoder : ObsObject
 {
+    private int _refCount = 0;
+    private readonly object _refLock = new();
     /// <summary>Known video encoder type IDs.</summary>
     public static class Types
     {
@@ -259,6 +262,53 @@ internal void SetVideo(VideoHandle video)
         ObsEncoder.obs_encoder_set_video(Handle, video);
     }
 
+    /// <summary>
+    /// Attaches this encoder to an output, incrementing the ref count.
+    /// </summary>
+    internal void Attach()
+    {
+        lock (_refLock)
+        {
+            _refCount++;
+        }
+    }
+
+    /// <summary>
+    /// Detaches this encoder from an output, decrementing the ref count.
+    /// When ref count reaches 0 and AutoDispose is enabled, the encoder is disposed.
+    /// </summary>
+    internal void Detach()
+    {
+        bool shouldDispose = false;
+        lock (_refLock)
+        {
+            _refCount--;
+            if (_refCount <= 0 && Obs.AutoDispose)
+            {
+                shouldDispose = true;
+            }
+        }
+
+        if (shouldDispose)
+        {
+            Dispose();
+        }
+    }
+
+    /// <summary>
+    /// Gets the current reference count (number of outputs using this encoder).
+    /// </summary>
+    public int RefCount
+    {
+        get
+        {
+            lock (_refLock)
+            {
+                return _refCount;
+            }
+        }
+    }
+
     /// <inheritdoc/>
     protected override void ReleaseHandle(nint handle)
     {

src/ObsKit.NET/Obs.cs

@@ -1,8 +1,10 @@
 using ObsKit.NET.Core;
+using ObsKit.NET.Encoders;
 using ObsKit.NET.Exceptions;
 using ObsKit.NET.Native;
 using ObsKit.NET.Native.Interop;
 using ObsKit.NET.Native.Types;
+using ObsKit.NET.Outputs;
 using ObsKit.NET.Scenes;
 using ObsKit.NET.Sources;
 
@@ -17,11 +19,31 @@ public static class Obs
     private static ObsContext? _context;
     private static readonly object _lock = new();
 
+    // Tracking for auto-management
+    private static readonly Dictionary<uint, Source> _channelSources = new();
+    private static readonly List<Output> _managedOutputs = new();
+
     /// <summary>
     /// Gets whether OBS is currently initialized.
     /// </summary>
     public static bool IsInitialized => ObsCore.obs_initialized();
 
+    /// <summary>
+    /// Gets or sets whether to automatically dispose sources and outputs on Shutdown.
+    /// Default is true.
+    /// </summary>
+    public static bool AutoDispose { get; set; } = true;
+
+    /// <summary>
+    /// Gets all sources currently assigned to output channels.
+    /// </summary>
+    public static IReadOnlyDictionary<uint, Source> ChannelSources => _channelSources;
+
+    /// <summary>
+    /// Gets all outputs being managed.
+    /// </summary>
+    public static IReadOnlyList<Output> ManagedOutputs => _managedOutputs;
+
     /// <summary>
     /// Gets the OBS version string.
     /// </summary>
@@ -118,6 +140,7 @@ public static ObsContext Initialize(Action<ObsConfiguration>? configure)
 
     /// <summary>
     /// Shuts down OBS and releases all resources.
+    /// Any remaining outputs will be stopped and sources will be disposed.
     /// </summary>
     public static void Shutdown()
     {
@@ -126,6 +149,30 @@ public static void Shutdown()
             if (_context == null)
                 return;
 
+            // Stop any remaining managed outputs
+            foreach (var output in _managedOutputs.ToList())
+            {
+                try
+                {
+                    if (output.IsActive)
+                        output.Stop();
+                }
+                catch { /* Ignore errors during cleanup */ }
+            }
+            _managedOutputs.Clear();
+
+            // Dispose all channel sources
+            foreach (var (channel, source) in _channelSources.ToList())
+            {
+                try
+                {
+                    ObsCore.obs_set_output_source(channel, ObsSourceHandle.Null);
+                    source.Dispose();
+                }
+                catch { /* Ignore errors during cleanup */ }
+            }
+            _channelSources.Clear();
+
             _context.Dispose();
             _context = null;
         }
@@ -154,30 +201,96 @@ public static void SetAudio(Action<AudioSettings> configure)
     }
 
     /// <summary>
-    /// Sets a source for an output channel. OBS uses channels 0-5 for different purposes:
+    /// Sets a source for an output channel. OBS uses channels 0-63 for different purposes:
     /// Channel 0: Primary video source (scene/game capture)
     /// Channel 1: Secondary video (display capture fallback)
-    /// Channels 2-5: Audio sources (microphone, desktop audio, etc.)
+    /// Channels 2+: Audio sources (microphone, desktop audio, etc.)
     /// </summary>
-    /// <param name="channel">The output channel (0-5).</param>
+    /// <param name="channel">The output channel (0-63).</param>
     /// <param name="source">The source to assign, or null to clear the channel.</param>
     public static void SetOutputSource(uint channel, Source? source)
     {
         ThrowIfNotInitialized();
+
+        lock (_lock)
+        {
+            // Remove existing source from tracking (but don't dispose - user may still want it)
+            _channelSources.Remove(channel);
+
+            if (source != null)
+            {
+                _channelSources[channel] = source;
+                source.AssignedChannel = channel;
+            }
+        }
+
         var handle = source != null ? (ObsSourceHandle)(nint)source.NativeHandle : ObsSourceHandle.Null;
         ObsCore.obs_set_output_source(channel, handle);
     }
 
     /// <summary>
     /// Clears a source from an output channel.
     /// </summary>
-    /// <param name="channel">The output channel to clear (0-5).</param>
+    /// <param name="channel">The output channel to clear (0-63).</param>
     public static void ClearOutputSource(uint channel)
     {
         ThrowIfNotInitialized();
+
+        lock (_lock)
+        {
+            if (_channelSources.TryGetValue(channel, out var source))
+            {
+                source.AssignedChannel = null;
+                _channelSources.Remove(channel);
+            }
+        }
+
         ObsCore.obs_set_output_source(channel, ObsSourceHandle.Null);
     }
 
+    /// <summary>
+    /// Adds an output to be managed. Managed outputs are tracked and can be auto-disposed on Shutdown.
+    /// </summary>
+    /// <typeparam name="T">The output type.</typeparam>
+    /// <param name="output">The output to manage.</param>
+    /// <returns>The same output for chaining.</returns>
+    public static T AddOutput<T>(T output) where T : Output
+    {
+        lock (_lock)
+        {
+            if (!_managedOutputs.Contains(output))
+            {
+                _managedOutputs.Add(output);
+            }
+        }
+        return output;
+    }
+
+    /// <summary>
+    /// Called when an output is stopped to remove it from tracking.
+    /// </summary>
+    internal static void OnOutputStopped(Output output)
+    {
+        lock (_lock)
+        {
+            _managedOutputs.Remove(output);
+        }
+    }
+
+    /// <summary>
+    /// Called when a source is disposed to remove it from channel tracking.
+    /// </summary>
+    internal static void OnSourceDisposed(Source source)
+    {
+        lock (_lock)
+        {
+            if (source.AssignedChannel.HasValue)
+            {
+                _channelSources.Remove(source.AssignedChannel.Value);
+            }
+        }
+    }
+
     /// <summary>
     /// Called by ObsContext when it's disposed directly (not through Obs.Shutdown).
     /// </summary>