Gerçek dünyadan bir eklenti: OBS

Resmî bir C# eklentisi, okumak için gösteriliyor

OBS eklentisi resmî C# eklentilerinden biridir: bakımcı tarafından derlenir ve imzalanır; sunucu bir C# eklentisini yalnızca bu imzayla yükler. Başka yazarların eklentileri JavaScript eklentileridir. Bu sayfa, tam bir entegrasyonun neye benzediğini gösterdiği için onu adım adım anlatır.

OBS eklentisi (id obs), OBS 28 ve üzerinde yerleşik gelen obs-websocket v5 üzerinden OBS Studio'yu kontrol eder. Depodaki en büyük eklentidir ve SDK'nın sunduğu neredeyse her şeyi kullanır; bu yüzden eğitimlerden sonra okunacak en iyi örnektir.

Neler sunar

• OBS kategorisinde 22 aksiyon: sahneler, stüdyo modu, geçişler, yayın, kayıt, tekrar arabelleği, sanal kamera, ses sessize alma ve seviyesi, sahne öğesi görünürlüğü ve metin kaynakları.
• obs. önekli yaklaşık 45 canlı değişken, örneğin obs.streaming, obs.stream.duration, obs.scene.current, obs.stats.fps; gelip giden öğeler için de obs.input.<slug>.muted ve obs.item.<scene>.<source>.visible.
• Bir ayar sayfası (Enabled, Server, Port, Password) ve bağlantı durumunu gösteren bir durum çubuğu öğesi.

WebSocket sunucusu açık, OBS 28 veya üzeri gerektirir (OBS'te Tools, WebSocket Server Settings). Eklentinin README dosyası her değişkeni ve aksiyonu listeler.

Giriş noktası

using MacroGrid.Plugin.Abstractions;

namespace MacroGrid.Plugin.Obs;

/// <summary>Entry point (plugin.json's "entry") — the host finds this type by reflection and instantiates it
/// with a parameterless constructor, then calls <see cref="Initialize"/> once.</summary>
public sealed class ObsPlugin : IPlugin
{
    public void Initialize(IPluginHost host)
    {
        var obs = new ObsConnection(host);
        host.RegisterVariableProvider(obs);
        host.RegisterSettingsPage(new ObsSettingsPage(host, obs));

        host.RegisterAction(new ObsSetSceneAction(obs));
        host.RegisterAction(new ObsSetPreviewSceneAction(obs));
        host.RegisterAction(new ObsStudioTransitionAction(obs));
        host.RegisterAction(new ObsToggleStudioModeAction(obs));
        host.RegisterAction(new ObsSetTransitionAction(obs));
        host.RegisterAction(new ObsSetProfileAction(obs));

        host.RegisterAction(new ObsStartStreamAction(obs));
        host.RegisterAction(new ObsStopStreamAction(obs));
        host.RegisterAction(new ObsToggleStreamAction(obs));
        host.RegisterAction(new ObsStartRecordAction(obs));
        host.RegisterAction(new ObsStopRecordAction(obs));
        host.RegisterAction(new ObsToggleRecordAction(obs));
        host.RegisterAction(new ObsPauseRecordAction(obs));
        host.RegisterAction(new ObsVirtualCamAction(obs));
        host.RegisterAction(new ObsReplayBufferAction(obs));
        host.RegisterAction(new ObsSaveReplayAction(obs));

        host.RegisterAction(new ObsSetMuteAction(obs));
        host.RegisterAction(new ObsToggleMuteAction(obs));
        host.RegisterAction(new ObsSetVolumeAction(obs));
        host.RegisterAction(new ObsAdjustVolumeAction(obs));

        host.RegisterAction(new ObsSetItemVisibilityAction(obs));
        host.RegisterAction(new ObsSetTextAction(obs));
    }
}

ObsConnection adlı tek bir nesne bağlantıyı yönetir. Değişken sağlayıcı olarak kaydedilir, ayar sayfasına ve her aksiyona verilir.

Dosya	Rol
ObsPlugin.cs	IPlugin: bağlantıyı oluşturur ve her şeyi kaydeder (yukarıda).
ObsConnection.cs	IVariableProvider ve IVariableCatalogSource. Eklentinin ömrü boyunca çalışır: bağlanır, değişkenleri güncel tutar, durum öğesini günceller ve üstel geri çekilmeyle (üst sınırlı) yeniden bağlanır.
ObsClient.cs, ObsAuth.cs, ObsJson.cs	Küçük bir obs-websocket v5 istemcisi: el sıkışma, kimlik doğrulama, istekler ve olaylar.
ObsState.cs	OBS'in bildirdiklerinin (sahneler, girişler, sahne öğeleri) önbelleği.
ObsActions.cs	Aksiyonlar. Her biri IActionHandler, IActionDescriptor ve açılır listeler için IOptionsSource uygular.
ObsSettings.cs	ObsSettings (DataDirectory içinde settings.json olarak saklanır) ve ObsSettingsPage : IPluginSettingsPage.

Kopyalamaya değer kalıplar

• Uzun soluklu bir sağlayıcı. ObsConnection.RunAsync, token'ı iptal edilene kadar çalışır. Durum öğesini host.CreateStatusItem("connection") ile oluşturur, değişkenleri kendisine verilen IVariableStore üzerinden yayınlar ve başarısız bir bağlantının yöntemi bitirmesine asla izin vermez: üst sınırlı üstel geri çekilmeyle yeniden dener ve bir ayar değişikliği onu erken uyandırır.
• Dinamik değişkenler kaldırılır. Bir OBS girişi veya sahne öğesi silindiğinde ya da yeniden adlandırıldığında eklenti, değişkenini store.Remove(name) ile kaldırır; böylece seçicide görünmeyi bırakır.
• Önbellekten açılır listeler. Aksiyonlar IOptionsSource uygular; sahne, giriş ve öğe listeleri OBS'in bildirdiklerinin önbelleğinden gelir, dolayısıyla canlı bir gidiş dönüşü beklemezler.
• Açık hatalar. Artık var olmayan bir şeyi hedefleyen bir aksiyon (OBS'te silinmiş bir sahne) açık bir mesajla başarısız olur. Sunucu bunu telefonda ve Düzenleyici'nin durum çubuğunda gösterir, böylece eskimiş bir düğme asla sessiz kalmaz.
• Ayarlar hemen uygulanır. Ayar sayfasının Save yöntemi settings.json dosyasını yazar ve bağlantıyı uyarır; böylece düzeltilmiş bir sunucu, port veya parola kısa süre içinde yeniden bağlanır.
• OBS olmadan testler. WebSocketBridgeForOBS/tests, eklentiyi sahte bir obs-websocket sunucusuna (FakeObsServer.cs) karşı çalıştırır. WebSocketBridgeForOBS/tests/MacroGrid.Plugin.Obs.Tests üzerinde dotnet test çalıştırın.

Eklentinin kullanıcıya görünen metinleri (aksiyon adları, form etiketleri, durum metni) İngilizce yazılmıştır ve WebSocketBridgeForOBS/locales/tr.json aracılığıyla Türkçeye çevrilir; kod, yorumlar ve dokümanlar İngilizcedir. Bu, depodaki her eklenti için geçerli kuraldır.

Bir düzende kullanmak

1. Eklentiyi kurun (Eklenti temelleri), dişli düğmesinden ayarlarını açın ve Enabled seçeneğini açın (eklenti devre dışı başlar).
2. Metni {obs.scene.current} olan bir düğme ekleyin ve sahne ayarlama aksiyonunu ona bağlayın.
3. Live {obs.stream.duration} etiketi ekleyin ve yayın aksiyonlarını bir toggle'a bağlayın.