Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

49.1 KB
Raw Blame
package nativehost

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"io"
	"log/slog"
	"slices"
	"strings"
	"sync"
	"time"
	"unicode/utf8"

	"github.com/TNTcraftHIM/Piik/internal/app/mediaedge"
	"github.com/TNTcraftHIM/Piik/internal/app/nativecapture"
	"github.com/TNTcraftHIM/Piik/internal/app/remoteinput"
	"github.com/TNTcraftHIM/Piik/internal/diagnostics"
	"github.com/TNTcraftHIM/Piik/internal/media/encoded"
	"github.com/TNTcraftHIM/Piik/internal/server/protocol"
	"github.com/pion/webrtc/v4"
)

const startTimeout = 5 * time.Second
const qualitySamplePeriod = 2 * time.Second

type CaptureState struct {
	State           string                        `json:"state"`
	HardwareOnly    bool                          `json:"hardwareOnly"`
	Codec           string                        `json:"codec"`
	AdapterIndex    *uint32                       `json:"adapterIndex,omitempty"`
	AdapterName     string                        `json:"adapterName,omitempty"`
	AdapterIdentity string                        `json:"adapterIdentity,omitempty"`
	EncoderIndex    *uint32                       `json:"encoderIndex,omitempty"`
	EncoderName     string                        `json:"encoderName,omitempty"`
	EncoderIdentity string                        `json:"encoderIdentity,omitempty"`
	ProfileLevelID  string                        `json:"profileLevelId,omitempty"`
	Width           uint32                        `json:"width,omitempty"`
	Height          uint32                        `json:"height,omitempty"`
	FPS             uint32                        `json:"fps,omitempty"`
	RestoreToken    string                        `json:"restoreToken,omitempty"`
	RemoteInput     bool                          `json:"remoteInput,omitempty"`
	Outputs         []nativecapture.OutputProfile `json:"outputs"`

	unavailableLayers []int
}

type Event struct {
	Current               func() bool
	SourceAudio           bool
	Microphone            bool
	Failed                bool
	Type                  string
	ShareID               string
	ConnectionID          string
	PublicationGeneration string
	Candidate             *webrtc.ICECandidateInit
	State                 string
	LocalType             string
	RemoteType            string
	NatTraversalPath      string
	Quality               *mediaedge.QualitySample
	PublicationQuality    *mediaedge.PublicationQualitySample
}

type Options struct {
	ShareID          string
	CaptureProcess   string
	Capture          CaptureProvider
	Video            nativecapture.VideoOptions
	Profile          QualityProfile
	AudioEnabled     bool
	ExcludeAudio     *nativecapture.CaptureTarget
	MicrophoneMixing bool
	EdgeCapacity     int
	BindAddress      string
	PortMapping      bool
	RemoteInput      *remoteinput.Manager
	Events           func(context.Context, Event)
}

type Session struct {
	shareID      string
	capture      CaptureProvider
	videoOptions nativecapture.VideoOptions
	profile      QualityProfile
	edgeCapacity int
	stream       CaptureStream
	audioStream  CaptureStream
	engine       *mediaedge.Engine
	source       *mediaedge.Source
	audioSource  *mediaedge.AudioSource
	mixer        *audioMix
	events       func(context.Context, Event)

	ctx         context.Context
	cancel      context.CancelFunc
	done        chan error
	ready       chan error
	videoActive chan struct{}

	mu           sync.Mutex
	updateMu     sync.Mutex
	edges        map[string]*mediaedge.Edge
	publications map[publicationKey]*mediaedge.Publication

	captureApplied     chan struct{}
	captureChanged     chan struct{}
	captureUnavailable []int

	audioChanged chan struct{}
	paused       bool
	closed       bool
	remoteInput  *remoteinput.Session
}

func Start(parent context.Context, options Options) (*Session, error) {
	if parent == nil {
		parent = context.Background()
	}
	if options.ShareID == "" || len(options.ShareID) > 256 {
		return nil, errors.New("native share identity is invalid")
	}
	if options.EdgeCapacity < 1 || options.EdgeCapacity > mediaedge.MaxRelayChildren {
		return nil, errors.New("native share edge capacity is invalid")
	}
	if !options.Profile.Valid() || options.Video.Profile != options.Profile.Video {
		return nil, errors.New("native share profile is invalid")
	}
	engine, err := mediaedge.NewEngine(mediaedge.EngineOptions{
		BindAddress:     options.BindAddress,
		IncludeLoopback: true,
		PortMapping:     options.PortMapping,
		InitialBitrate:  int(options.Profile.Video.Bitrate),
	})
	if err != nil {
		return nil, err
	}
	options.Video.OutputGroups = min(options.EdgeCapacity, nativecapture.MaxOutputGroups)
	capture := options.Capture
	if capture == nil {
		capture = processCapture{options.CaptureProcess}
	}
	stream, err := capture.Video(parent, options.Video)
	if err != nil {
		_ = engine.Close()
		return nil, err
	}
	preparing := stream
	defer func() { capturePreparationDone(preparing) }()
	ctx, cancel := context.WithCancel(parent)
	session := &Session{
		shareID:        options.ShareID,
		capture:        capture,
		videoOptions:   options.Video,
		profile:        options.Profile,
		edgeCapacity:   options.EdgeCapacity,
		stream:         stream,
		engine:         engine,
		events:         options.Events,
		ctx:            ctx,
		cancel:         cancel,
		done:           make(chan error, 1),
		ready:          make(chan error, 1),
		videoActive:    make(chan struct{}),
		edges:          make(map[string]*mediaedge.Edge),
		audioChanged:   make(chan struct{}, 1),
		captureChanged: make(chan struct{}, 1),
		remoteInput:    options.RemoteInput.NewSession(),
	}
	session.syncRemoteInputSource(nil)
	// Drain video while the optional audio process initializes. Otherwise a full
	// video pipe can stall the platform capture service that audio also needs.
	videoDone := make(chan error, 1)
	// Source audio may still be awaiting platform permission when video ends.
	// Its context lives with video, including after a successful start.
	audioCtx, cancelAudio := context.WithCancel(ctx)
	go func() {
		videoDone <- session.runVideo()
		cancelAudio()
	}()
	var timeout <-chan time.Time
	if options.Video.Target.Kind != "picker" {
		timer := time.NewTimer(startTimeout)
		defer timer.Stop()
		timeout = timer.C
	}
	select {
	case err = <-session.ready:
	case <-timeout:
		err = errors.New("native capture did not start in time")
	case <-parent.Done():
		err = parent.Err()
	}
	if err != nil {
		cancel()
		captureErr := stream.Close()
		<-videoDone
		session.retire()
		return nil, errors.Join(err, captureErr)
	}
	// Legacy pages choose a fixed audio shape in the start response. Mixed audio
	// already has a stable output, so its optional input can attach after return.
	var audioStream CaptureStream
	if options.AudioEnabled && !options.MicrophoneMixing {
		var audioErr error
		audioStream, audioErr = session.startSourceAudio(audioCtx, options.Video.Target, options.ExcludeAudio)
		if audioErr != nil {
			slog.DebugContext(ctx, "piik-client", "event", "capture-audio-unavailable", "share", diagnostics.ID(options.ShareID), diagnostics.Error(audioErr))
		}
		session.audioStream = audioStream
	}
	select {
	case videoErr := <-videoDone:
		cancel()
		_ = stream.Close()
		if audioStream != nil {
			_ = audioStream.Close()
		}
		session.retire()
		return nil, videoErr
	default:
	}
	if audioStream != nil || options.MicrophoneMixing {
		audioSource, audioErr := engine.NewAudioSource(
			mediaedge.PhysicalSourceCapacity(options.EdgeCapacity), options.Profile.AudioBitrate,
		)
		if audioErr != nil {
			slog.DebugContext(ctx, "piik-client", "event", "capture-audio-source-failed", "share", diagnostics.ID(options.ShareID), diagnostics.Error(audioErr))
			if audioStream != nil {
				_ = audioStream.Close()
			}
			audioStream = nil
			session.audioStream = nil
		} else {
			session.audioSource = audioSource
		}
	}
	if options.MicrophoneMixing {
		if session.audioSource == nil {
			cancel()
			_ = stream.Close()
			<-videoDone
			session.retire()
			return nil, errors.New("native mixed audio could not start")
		}
		session.mixer = &audioMix{ctx: ctx, output: session.audioSource, emit: session.emit, shareID: session.shareID, gain: 1}
		session.mixer.setSource(audioStream)
	}
	var audioStarting chan struct{}
	if options.AudioEnabled && session.mixer != nil {
		audioStarting = make(chan struct{})
		preparing = nil // The input startup now owns the interactive preparation.
		go func() {
			defer close(audioStarting)
			defer capturePreparationDone(stream)
			// Waiting for the platform must not hold up a source or quality change.
			// A later source-audio commit supersedes this initial input request.
			select {
			case <-session.videoActive:
			case <-session.audioChanged:
				return
			case <-audioCtx.Done():
				return
			}
			session.updateMu.Lock()
			defer session.updateMu.Unlock()
			select {
			case <-session.audioChanged:
				return
			default:
			}
			input, audioErr := session.startSourceAudio(audioCtx, options.Video.Target, options.ExcludeAudio)
			if audioErr != nil {
				slog.DebugContext(ctx, "piik-client", "event", "capture-audio-unavailable", "share", diagnostics.ID(options.ShareID), diagnostics.Error(audioErr))
				return
			}
			session.mu.Lock()
			if audioCtx.Err() != nil || session.closed {
				session.mu.Unlock()
				_ = input.Close()
				return
			}
			session.audioStream = input
			session.mu.Unlock()
			session.mixer.setSource(input)
		}()
	}
	go session.run(videoDone, audioStarting)
	if err := ctx.Err(); err != nil {
		_ = session.Close()
		return nil, err
	}
	return session, nil
}

func (session *Session) ShareID() string {
	return session.shareID
}

func (session *Session) Codec() string {
	session.mu.Lock()
	defer session.mu.Unlock()
	if session.source == nil {
		return ""
	}
	return session.source.Codec()
}

func (session *Session) HasAudio() bool {
	session.mu.Lock()
	defer session.mu.Unlock()
	return !session.closed && session.audioSource != nil
}

func (session *Session) PrepareEdge(
	connectionID string,
	iceServers []webrtc.ICEServer,
	punched bool,
) (webrtc.SessionDescription, error) {
	return session.prepareEdge(connectionID, iceServers, "", punched)
}

func (session *Session) PrepareLocalEdge(
	connectionID, offerID string,
	restart bool,
) (webrtc.SessionDescription, error) {
	if restart {
		edge := session.edge(connectionID)
		if edge == nil {
			return webrtc.SessionDescription{}, errors.New("native local media edge does not exist")
		}
		return edge.CreateLocalOffer(session.ctx, offerID, true)
	}
	return session.prepareEdge(connectionID, nil, offerID, false)
}

func (session *Session) prepareEdge(
	connectionID string,
	iceServers []webrtc.ICEServer,
	localOfferID string,
	punched bool,
) (webrtc.SessionDescription, error) {
	session.mu.Lock()
	if session.closed || session.edges[connectionID] != nil {
		session.mu.Unlock()
		return webrtc.SessionDescription{}, errors.New("native media edge is unavailable")
	}
	session.mu.Unlock()
	var edge *mediaedge.Edge
	current := func() bool {
		session.mu.Lock()
		defer session.mu.Unlock()
		return !session.closed && edge != nil && session.edges[connectionID] == edge
	}
	created, err := session.engine.NewEdge(session.source, mediaedge.EdgeOptions{
		ConnectionID: connectionID,
		ICEServers:   iceServers,
		Audio:        session.audioSource,
		Local:        localOfferID != "",
		Punched:      punched,
		Events: mediaedge.EdgeEvents{
			LocalCandidate: func(candidate *webrtc.ICECandidateInit) {
				session.emit(Event{
					Current: current,
					Type:    "edge-candidate", ShareID: session.shareID,
					ConnectionID: connectionID, Candidate: candidate,
				})
			},
			ConnectionState: func(state webrtc.PeerConnectionState, pair *mediaedge.SelectedPair, isCurrentState func(webrtc.PeerConnectionState) bool) {
				session.emit(Event{
					Current: func() bool { return current() && isCurrentState(state) },
					Type:    "edge-state", ShareID: session.shareID,
					ConnectionID: connectionID, State: state.String(),
				})
				if pair != nil {
					session.emit(Event{
						Current: func() bool { return current() && isCurrentState(state) },
						Type:    "edge-path", ShareID: session.shareID,
						ConnectionID:     connectionID,
						LocalType:        pair.Local.String(),
						RemoteType:       pair.Remote.String(),
						NatTraversalPath: pair.NatTraversalPath,
					})
				}
			},
		},
	})
	if err != nil {
		return webrtc.SessionDescription{}, err
	}
	session.mu.Lock()
	if session.closed || session.edges[connectionID] != nil {
		session.mu.Unlock()
		_ = created.Close()
		return webrtc.SessionDescription{}, errors.New("native media edge is unavailable")
	}
	edge = created
	session.edges[connectionID] = edge
	session.mu.Unlock()
	var offer webrtc.SessionDescription
	if session.remoteInput != nil {
		channel, channelErr := edge.OpenDataChannel(remoteinput.ChannelLabel)
		if channelErr == nil {
			edge.OnInputTransportLost(session.remoteInput.Attach(connectionID, channel))
		}
	}
	if localOfferID != "" {
		offer, err = edge.CreateLocalOffer(session.ctx, localOfferID, false)
	} else {
		offer, err = edge.CreateOffer()
	}
	if err != nil {
		session.CloseEdge(connectionID)
		return webrtc.SessionDescription{}, err
	}
	return offer, nil
}

func (session *Session) SetAnswer(connectionID string, answer webrtc.SessionDescription, offerID string) error {
	edge := session.edge(connectionID)
	if edge == nil {
		return errors.New("native media edge does not exist")
	}
	return edge.SetAnswer(answer, offerID)
}

func (session *Session) AddCandidate(
	connectionID string,
	candidate *webrtc.ICECandidateInit,
) error {
	edge := session.edge(connectionID)
	if edge == nil {
		// Candidates can arrive after an edge has been retired. They are
		// disposable input, not a reason to tear down the share session.
		return nil
	}
	return edge.AddRemoteCandidate(candidate)
}

func (session *Session) SetPaused(paused bool) {
	session.remoteInput.Pause(paused)
	session.mu.Lock()
	if session.closed {
		session.mu.Unlock()
		return
	}
	session.paused = paused
	if session.mixer != nil {
		session.mixer.setPaused(paused)
	}
	source := session.source
	session.mu.Unlock()
	if !paused {
		source.RequestRecoveryFrame()
	}
}

func (session *Session) UpdateProfile(profile QualityProfile) error {
	if !profile.Valid() {
		return errors.New("native share profile is invalid")
	}
	session.updateMu.Lock()
	defer session.updateMu.Unlock()

	session.mu.Lock()
	if session.closed || session.ctx.Err() != nil {
		session.mu.Unlock()
		return errors.New("native share is unavailable")
	}
	if session.profile == profile {
		session.mu.Unlock()
		return nil
	}
	previousProfile := session.profile
	options := session.videoOptions
	options.Profile = profile.Video
	session.mu.Unlock()
	if profile.Video == previousProfile.Video {
		if session.audioSource != nil && profile.AudioBitrate != previousProfile.AudioBitrate {
			if err := session.audioSource.SetBitrate(profile.AudioBitrate); err != nil {
				return err
			}
		}
		session.mu.Lock()
		if session.closed || session.ctx.Err() != nil {
			session.mu.Unlock()
			return errors.New("native share is unavailable")
		}
		session.profile = profile
		session.mu.Unlock()
		return nil
	}

	// Updating an existing source never waits for an interactive picker.
	replacement, state, err := session.prepareVideo(session.ctx, options, false, true)
	if err != nil {
		return err
	}
	defer capturePreparationDone(replacement)
	if session.audioSource != nil && profile.AudioBitrate != previousProfile.AudioBitrate {
		if err = session.audioSource.SetBitrate(profile.AudioBitrate); err != nil {
			_ = replacement.Close()
			return err
		}
	}

	return session.commitCapture(
		options,
		profile,
		replacement,
		state,
		nil,
		false,
		nil,
	)
}

func (session *Session) ReplaceSource(
	options nativecapture.VideoOptions,
	audioEnabled bool,
	excludeAudio *nativecapture.CaptureTarget,
) error {
	session.updateMu.Lock()
	defer session.updateMu.Unlock()
	session.mu.Lock()
	if session.closed {
		session.mu.Unlock()
		return errors.New("native share is unavailable")
	}
	profile := session.profile
	options.Codec = session.videoOptions.Codec
	options.AdapterIndex = session.videoOptions.AdapterIndex
	options.EncoderIndex = session.videoOptions.EncoderIndex
	options.OutputGroups = min(session.edgeCapacity, nativecapture.MaxOutputGroups)
	hasAudio := session.audioSource != nil && session.audioStream != nil
	currentTarget := session.videoOptions.Target
	audioOnly := options.Target.Kind != "picker" &&
		options.Target.Kind == currentTarget.Kind && options.Target.SourceID == currentTarget.SourceID &&
		options.Target.PID == currentTarget.PID && options.Target.CreationTime == currentTarget.CreationTime &&
		options.ShowCaptureBorder == session.videoOptions.ShowCaptureBorder
	session.mu.Unlock()
	if session.mixer == nil && audioEnabled != hasAudio {
		return errors.New("native source audio availability cannot change while sharing")
	}
	if audioEnabled && session.videoActive != nil {
		select {
		case <-session.videoActive:
		default:
			return errors.New("native source audio is unavailable until video becomes active")
		}
	}
	if excludeAudio != nil {
		if session.mixer == nil {
			return errors.New("native audio exclusion requires mixed audio")
		}
		// A privacy change retires the old source before preparation. Failure must
		// leave it silent rather than retaining unfiltered audio; video/mic stay live.
		session.mu.Lock()
		previousAudio := session.audioStream
		session.audioStream = nil
		session.mu.Unlock()
		session.mixer.setSource(nil)
		if previousAudio != nil {
			_ = previousAudio.Close()
		}
	}
	options.Profile = profile.Video
	options.RestoreToken = ""
	var replacement CaptureStream
	var state CaptureState
	var err error
	// Admit audio before candidate video can fill its unread queue and block a
	// platform handler that also starts audio. The current picture stays drained.
	var replacementAudio CaptureStream
	if audioEnabled {
		replacementAudio, err = session.startSourceAudio(
			session.ctx,
			options.Target,
			excludeAudio,
		)
		if err != nil {
			return errors.New("native source audio could not start")
		}
	}
	if !audioOnly {
		replacement, state, err = session.prepareVideo(session.ctx, options, options.Target.Kind == "picker", false)
		if err != nil {
			if replacementAudio != nil {
				_ = replacementAudio.Close()
			}
			return err
		}
		defer capturePreparationDone(replacement)
		// Preparation still belongs to the old source. Retire its authorization
		// only when the replacement is ready to enter the capture transaction.
		session.remoteInput.SetTarget(nativecapture.CaptureTarget{}, nil)
		defer session.syncRemoteInputSource(nil)
	}
	return session.commitCapture(
		options,
		profile,
		replacement,
		state,
		replacementAudio,
		true,
		nil,
	)
}

func (session *Session) RemoteInputChanges() <-chan struct{} {
	return session.remoteInput.Changes()
}

func (session *Session) RemoteInputState() remoteinput.State {
	return session.remoteInput.State()
}

// Reserve the intent synchronously, before dispatch starts asynchronous OS work.
func (session *Session) PrepareRemoteInputPolicy(mode, password string, coPlay bool) (func() error, error) {
	change, err := session.remoteInput.BeginPolicy(session.ctx, mode, password, coPlay)
	if err != nil {
		return nil, err
	}
	return func() error {
		defer change.Close()
		if session.remoteInput.UsesCaptureInput() && mode != "off" {
			session.updateMu.Lock()
			defer session.updateMu.Unlock()
			session.mu.Lock()
			options, profile := session.videoOptions, session.profile
			closed := session.closed
			session.mu.Unlock()
			if closed {
				return errors.New("native share is unavailable")
			}
			if !options.RemoteInput {
				// Only enabling control requests the combined screen/input permission.
				// The pending intent can retire without ending the current picture.
				options.RemoteInput, options.RestoreToken = true, ""
				replacement, state, err := session.prepareVideo(change.Context(), options, true, false)
				if err != nil {
					return err
				}
				defer capturePreparationDone(replacement)
				if err := change.Context().Err(); err != nil {
					_ = replacement.Close()
					return err
				}
				if err = session.commitCapture(options, profile, replacement, state, nil, false, change); err != nil {
					return err
				}
			}
		}
		return change.Apply()
	}, nil
}

func (session *Session) SetRemoteInputPeers(peers []protocol.RemoteInputPeer) error {
	return session.remoteInput.SetPeers(peers)
}

func (session *Session) DecideRemoteInput(id string, allow bool) error {
	return session.remoteInput.Decide(id, allow)
}

func (session *Session) SetRemoteInputSimultaneous(enabled bool) error {
	return session.remoteInput.SetSimultaneous(enabled)
}

func (session *Session) syncRemoteInputSource(change *remoteinput.PolicyChange) {
	session.mu.Lock()
	target := session.videoOptions.Target
	capture, _ := session.stream.(*nativecapture.Stream)
	session.mu.Unlock()
	if change != nil {
		change.SetTarget(target, capture)
	} else {
		session.remoteInput.SetTarget(target, capture)
	}
}

func startAudioCapture(
	ctx context.Context,
	captureProcess string,
	target nativecapture.CaptureTarget,
	excludeAudio *nativecapture.CaptureTarget,
) (*nativecapture.Stream, error) {
	if excludeAudio != nil {
		return nativecapture.StartAudio(ctx, captureProcess, *excludeAudio, true)
	}
	if target.Kind == "display" || target.Kind == "picker" {
		return nativecapture.StartSystemAudio(ctx, captureProcess)
	}
	return nativecapture.StartAudio(ctx, captureProcess, target, false)
}

func (session *Session) startSourceAudio(
	ctx context.Context,
	target nativecapture.CaptureTarget,
	excludeAudio *nativecapture.CaptureTarget,
) (CaptureStream, error) {
	// A starting status admits control and progress; only active proves that
	// platform video initialization finished. Keep draining video during this wait.
	if session.videoActive != nil {
		select {
		case <-session.videoActive:
		case <-ctx.Done():
			return nil, ctx.Err()
		}
	}
	if err := ctx.Err(); err != nil {
		return nil, err
	}
	return session.capture.Audio(ctx, target, excludeAudio)
}

// Interactive platforms retain their preparation UI until the whole operation,
// including source audio and capture commit, has finished.
func capturePreparationDone(stream CaptureStream) {
	if preparation, ok := stream.(interface{ PreparationDone() }); ok {
		preparation.PreparationDone()
	}
}

func (session *Session) prepareVideo(
	ctx context.Context,
	options nativecapture.VideoOptions,
	interactive bool,
	allowQuiet bool,
) (CaptureStream, CaptureState, error) {
	if err := ctx.Err(); err != nil {
		return nil, CaptureState{}, err
	}
	options.OutputGroups = min(session.edgeCapacity, nativecapture.MaxOutputGroups)
	// Preparation can be cancelled independently. Installed capture always lives
	// with the share; cancelling a permission request must not kill its process.
	replacement, err := session.capture.Video(
		session.ctx,
		options,
	)
	if err != nil {
		return nil, CaptureState{}, captureProfileFailure(ctx, options.Profile, "process-start",
			errors.New("native capture could not start"))
	}
	state, err := waitForCaptureProfile(
		ctx,
		replacement,
		options.Profile,
		options.Codec,
		interactive,
		allowQuiet,
	)
	if err != nil {
		return nil, CaptureState{}, errors.Join(err, replacement.Close())
	}
	if options.RemoteInput && !state.RemoteInput {
		_ = replacement.Close()
		return nil, CaptureState{}, errors.New("desktop did not grant remote input")
	}
	return replacement, state, nil
}

func (session *Session) commitCapture(
	options nativecapture.VideoOptions,
	profile QualityProfile,
	replacement CaptureStream,
	state CaptureState,
	replacementAudio CaptureStream,
	replaceAudio bool,
	inputChange *remoteinput.PolicyChange,
) error {
	session.mu.Lock()
	if session.closed || session.ctx.Err() != nil {
		session.mu.Unlock()
		if replacement != nil {
			_ = replacement.Close()
		}
		if replacementAudio != nil {
			_ = replacementAudio.Close()
		}
		return errors.New("native share is unavailable")
	}
	previous := session.stream
	previousAudio := session.audioStream
	var applied chan struct{}
	// A source-audio change retains the current capture generation and encoder.
	if replacement != nil {
		if state.RestoreToken != "" {
			options.RestoreToken = state.RestoreToken
		}
		state.applyBackend(&options)
		session.stream = replacement
		applied = make(chan struct{})
		session.captureApplied = applied
		session.captureUnavailable = state.unavailableLayers
		session.videoOptions = options
		session.profile = profile
		select {
		case session.captureChanged <- struct{}{}:
		default:
		}
	}
	if replaceAudio {
		session.audioStream = replacementAudio
		select {
		case session.audioChanged <- struct{}{}:
		default:
		}
	}
	session.mu.Unlock()

	if replaceAudio && session.mixer != nil {
		session.mixer.setSource(replacementAudio)
	}
	if replaceAudio && previousAudio != nil {
		_ = previousAudio.Close()
	}
	if replacement == nil {
		return nil
	}
	// A Portal stream owns input permission as well as the picture. Retire its
	// grant before closing it, then bind the replacement through the same owner.
	if session.remoteInput.UsesCaptureInput() {
		if inputChange != nil {
			inputChange.SetTarget(nativecapture.CaptureTarget{}, nil)
		} else {
			session.remoteInput.SetTarget(nativecapture.CaptureTarget{}, nil)
		}
		defer session.syncRemoteInputSource(inputChange)
	}
	_ = replacement.RequestKeyFrame(-1)
	_ = previous.Close()
	select {
	case <-applied:
	case <-session.ctx.Done():
		return session.ctx.Err()
	}
	if err := session.ctx.Err(); err != nil {
		return err
	}
	return nil
}

func (session *Session) prepareCaptureRecovery(failed CaptureStream) error {
	session.updateMu.Lock()
	defer session.updateMu.Unlock()
	session.mu.Lock()
	if session.closed || session.ctx.Err() != nil {
		session.mu.Unlock()
		return errors.New("native share is unavailable")
	}
	if session.stream != failed {
		session.mu.Unlock()
		return nil
	}
	options, profile := session.videoOptions, session.profile
	session.mu.Unlock()
	replacement, state, err := session.prepareVideo(session.ctx, options, false, false)
	if err != nil {
		return err
	}
	defer capturePreparationDone(replacement)
	return session.commitCapture(options, profile, replacement, state, nil, false, nil)
}

// Only the video reader installs source metadata, after leaving the old input.
// The update response waits for this exact stream's installation, not its process.
func (session *Session) installCapture(next CaptureStream) error {
	session.mu.Lock()
	unavailable := session.captureUnavailable
	session.mu.Unlock()
	session.source.BeginGeneration()
	if err := configureCaptureOutputs(session.source, next.Outputs()); err != nil {
		return err
	}
	// Preparation has consumed these events. Apply them to the new generation
	// before acknowledging it, just as the live reader handles unavailable layers.
	for _, layer := range unavailable {
		if err := session.disableCaptureLayer(next, layer); err != nil {
			return err
		}
	}
	session.mu.Lock()
	if session.stream == next && session.captureApplied != nil {
		close(session.captureApplied)
		session.captureApplied = nil
		session.captureUnavailable = nil
	}
	session.mu.Unlock()
	session.emit(Event{Type: "capture-state", ShareID: session.shareID, State: "active"})
	return nil
}

func (session *Session) disableCaptureLayer(stream CaptureStream, layer int) error {
	session.mu.Lock()
	if session.stream != stream || session.closed || session.ctx.Err() != nil {
		session.mu.Unlock()
		return nil
	}
	// Accept failure atomically with capture selection. Closing transports may
	// wait for callbacks, so only the source-state change belongs under this lock.
	retire, err := session.source.MarkLayerUnavailable(layer)
	session.mu.Unlock()
	if retire != nil {
		retire()
	}
	return err
}

func (session *Session) CloseEdge(connectionID string) {
	session.engine.ClosePunch(connectionID)
	session.mu.Lock()
	edge := session.edges[connectionID]
	delete(session.edges, connectionID)
	session.mu.Unlock()
	if edge != nil {
		_ = edge.Close()
	}
}

func (session *Session) Done() <-chan error {
	return session.done
}

func (session *Session) Close() error {
	session.cancel()
	session.updateMu.Lock()
	session.mu.Lock()
	if session.closed {
		session.mu.Unlock()
		session.updateMu.Unlock()
		_, _ = <-session.done
		return nil
	}
	session.closed = true
	session.edges = make(map[string]*mediaedge.Edge)
	session.mu.Unlock()
	// Closed/cancelled rejects further updates. Pending startup must be able to
	// acquire the update lock and finish before run can complete retirement.
	session.updateMu.Unlock()
	session.retire()
	_, _ = <-session.done
	return nil
}

// Both explicit Close and source termination retire these idempotent owners.
// Do not wait for run here: Close uses this to unblock run's readers.
func (session *Session) retire() {
	session.remoteInput.Close()
	session.mu.Lock()
	source, stream := session.source, session.stream
	audioSource, audioStream := session.audioSource, session.audioStream
	session.mu.Unlock()
	if source != nil {
		_ = source.Close()
	}
	_ = stream.Close()
	if audioStream != nil {
		_ = audioStream.Close()
	}
	if audioSource != nil {
		_ = audioSource.Close()
	}
	_ = session.engine.Close()
}

func (session *Session) edge(connectionID string) *mediaedge.Edge {
	session.mu.Lock()
	defer session.mu.Unlock()
	if session.closed {
		return nil
	}
	return session.edges[connectionID]
}

func (session *Session) run(videoDone <-chan error, audioStarting <-chan struct{}) {
	audioDone := make(chan struct{})
	qualityDone := make(chan struct{})
	go func() {
		session.runQuality()
		close(qualityDone)
	}()
	if session.mixer != nil {
		go func() { session.mixer.run(); close(audioDone) }()
	} else if session.audioSource == nil {
		// The session's output shape is fixed; source inputs can change concurrently.
		close(audioDone)
	} else {
		go func() {
			session.runAudio()
			close(audioDone)
		}()
	}
	result := <-videoDone
	session.mu.Lock()
	closed := session.closed
	session.mu.Unlock()
	if closed || session.ctx.Err() != nil {
		// Closing this owner or its parent is a clean end, even if stopping the
		// capture made the video reader return an error.
		result = nil
	}
	session.cancel()
	if audioStarting != nil {
		<-audioStarting
	}
	session.mu.Lock()
	audioStream := session.audioStream
	session.mu.Unlock()
	if audioStream != nil {
		_ = audioStream.Close()
	}
	<-audioDone
	<-qualityDone
	session.retire()
	level := slog.LevelDebug
	if result != nil && !errors.Is(result, nativecapture.ErrSourceCanceled) {
		level = slog.LevelWarn
	}
	if slog.Default().Enabled(session.ctx, level) {
		slog.Log(session.ctx, level, "piik-client", "event", "share-ended", "share", diagnostics.ID(session.shareID), "failed", result != nil, diagnostics.Error(result))
	}
	session.done <- result
	close(session.done)
}

func (session *Session) runVideo() error {
	ready := false
	activeSeen := false
	markActive := func() {
		if !activeSeen && session.videoActive != nil {
			close(session.videoActive)
		}
		activeSeen = true
	}
	current := session.currentStream()
	fail := func(err error) error {
		// A final frame/control error can arrive before the process waiter joins.
		// Preserve that read/validation error and the selected helper's exit cause.
		if current != nil {
			err = errors.Join(err, current.Close())
		}
		if !ready {
			session.ready <- err
		}
		return err
	}
	changeStream := func(next CaptureStream) error {
		if err := session.installCapture(next); err != nil {
			return err
		}
		current = next
		// prepareVideo consumed and verified this replacement's active status.
		markActive()
		return nil
	}
	readFrames := func() error {
		for current != nil {
			frame, err := current.Read()
			if err != nil {
				// Retirement joins the helper's exit and its sanitized failure codes.
				// Recheck ownership afterward: a replacement can commit during Close.
				_ = current.Close()
				next := session.currentStream()
				if next != nil && next != current {
					if err = changeStream(next); err != nil {
						return fail(err)
					}
					continue
				}
				slog.DebugContext(session.ctx, "piik-client", "event", "capture-video-read-ended",
					"share", diagnostics.ID(session.shareID), "canceled", session.ctx.Err() != nil, "eof", errors.Is(err, io.EOF), diagnostics.Error(err))
				if errors.Is(err, nativecapture.ErrSourceCanceled) {
					return fail(err)
				}
				return fail(errors.Join(errors.New("native capture stopped unexpectedly"), err))
			}
			if next := session.currentStream(); next != current {
				if next != nil {
					if err = changeStream(next); err != nil {
						return fail(err)
					}
				}
				continue
			}
			switch frame.Kind {
			case nativecapture.FrameStatus:
				status, statusErr := decodeCaptureState(frame.Data)
				if statusErr != nil {
					return fail(statusErr)
				}
				if !slices.Equal(status.Outputs, current.Outputs()) {
					return fail(errors.New("native capture outputs were not applied"))
				}
				session.mu.Lock()
				if session.closed {
					session.mu.Unlock()
					return fail(errors.New("native share stopped"))
				}
				if session.stream != current {
					session.mu.Unlock()
					continue
				}
				if session.source == nil {
					if session.videoOptions.Codec != "auto" && session.videoOptions.Codec != status.Codec {
						session.mu.Unlock()
						return fail(errors.New("native capture codec was not applied"))
					}
					source, sourceErr := session.engine.NewSource(status.Codec, mediaedge.PhysicalSourceCapacity(session.edgeCapacity), min(2, len(status.Outputs)), func(layers []int) {
						if stream := session.currentStream(); stream != nil {
							for _, layer := range layers {
								_ = stream.RequestKeyFrame(layer)
							}
						}
					})
					if sourceErr != nil {
						session.mu.Unlock()
						return fail(sourceErr)
					}
					if sourceErr = configureCaptureOutputs(source, status.Outputs); sourceErr != nil {
						session.mu.Unlock()
						_ = source.Close()
						return fail(sourceErr)
					}
					session.source = source
					session.videoOptions.Codec = status.Codec
				} else if session.source.Codec() != status.Codec {
					session.mu.Unlock()
					return fail(errors.New("native capture codec changed within a share"))
				}
				if status.State == "active" {
					markActive()
					if status.RestoreToken != "" {
						session.videoOptions.RestoreToken = status.RestoreToken
					}
				}
				status.applyBackend(&session.videoOptions)
				session.mu.Unlock()
				slog.Debug("piik-client", "event", "capture-state", "state", status.State, "codec", status.Codec,
					"share", diagnostics.ID(session.shareID), "width", status.Width, "height", status.Height, "fps", status.FPS,
					"hardware", status.HardwareOnly, "adapterIndex", status.AdapterIndex, "encoderIndex", status.EncoderIndex,
					"adapterName", diagnostics.SafeText(status.AdapterName), "encoderName", diagnostics.SafeText(status.EncoderName),
					"profileLevelId", status.ProfileLevelID, "outputs", status.Outputs)
				session.emit(Event{Type: "capture-state", ShareID: session.shareID, State: status.State})
				if !ready {
					ready = true
					session.ready <- nil
				}
			case nativecapture.FrameBegin:
				if session.source == nil {
					return fail(errors.New("native capture input arrived before its state"))
				}
				plan, beginErr := session.source.BeginFrame(frame.Timestamp)
				if beginErr != nil {
					return fail(beginErr)
				}
				session.mu.Lock()
				paused := session.paused
				session.mu.Unlock()
				if paused {
					clear(plan.Active)
				}
				controlErr := applyOutputPlan(current, plan, activeSeen)
				if controlErr != nil && session.currentStream() == current {
					return fail(controlErr)
				}
			case nativecapture.FrameH264, nativecapture.FrameVP8:
				if session.source == nil ||
					(frame.Kind == nativecapture.FrameH264) != (session.source.Codec() == "h264") {
					return fail(errors.New("native video frame does not match its source codec"))
				}
				if formatErr := session.source.SetFormat(frame.Layer, frame.Width, frame.Height); formatErr != nil {
					return fail(formatErr)
				}
				// Edge state owns write failures; one retired edge cannot stop siblings.
				session.mu.Lock()
				paused := session.paused
				session.mu.Unlock()
				if !paused {
					writeErr := session.source.WriteVideo(frame.Layer, encoded.Frame{
						Data: frame.Data, PTS: frame.Timestamp, Duration: frame.Duration, Recovery: frame.KeyFrame,
					})
					if errors.Is(writeErr, encoded.ErrInvalidTimestamp) {
						return fail(writeErr)
					}
				}
			case nativecapture.FrameLayerUnavailable:
				slog.DebugContext(session.ctx, "piik-client", "event", "capture-output-unavailable",
					"share", diagnostics.ID(session.shareID), "layer", frame.Layer, "detail", diagnostics.SafeText(string(frame.Data)))
				if session.source == nil {
					return fail(errors.New("native output ended before its source state"))
				}
				if err = session.disableCaptureLayer(current, frame.Layer); err != nil {
					return fail(err)
				}
			case nativecapture.FramePCM:
				return fail(errors.New("native video process emitted audio"))
			default:
				return fail(errors.New("native video process emitted an unknown frame"))
			}
		}
		return fail(errors.New("native capture stopped unexpectedly"))
	}
	for {
		err := readFrames()
		failure := nativecapture.FailureDetails(err)
		if !activeSeen || session.ctx.Err() != nil || errors.Is(err, nativecapture.ErrSourceCanceled) || failure == nil {
			return err
		}
		switch failure.HRESULT {
		case "0x887a0005", "0x887a0006", "0x887a0007", "0x887a0020": // DXGI device removed, hung, reset, driver internal error.
		default:
			return err
		}
		slog.DebugContext(session.ctx, "piik-client", "event", "capture-device-recovering",
			"share", diagnostics.ID(session.shareID), "stage", failure.Stage, "hresult", failure.HRESULT, diagnostics.Error(err))
		recovered := make(chan error, 1)
		go func(failed CaptureStream) { recovered <- session.prepareCaptureRecovery(failed) }(current)
		// Updates retain the operation lock until this reader installs their
		// metadata. Keep serving that handoff while recovery waits for the lock.
		var recoveryErr error
	waiting:
		for {
			select {
			case recoveryErr = <-recovered:
				break waiting
			case <-session.captureChanged:
				if next := session.currentStream(); next != nil && next != current {
					if recoveryErr = changeStream(next); recoveryErr != nil {
						session.cancel()
						<-recovered
						break waiting
					}
				}
			case <-session.ctx.Done():
				recoveryErr = session.ctx.Err()
				<-recovered
				break waiting
			}
		}
		if recoveryErr != nil {
			return errors.Join(err, recoveryErr)
		}
	}
}

func configureCaptureOutputs(source *mediaedge.Source, outputs []nativecapture.OutputProfile) error {
	ceilings := make([]uint32, len(outputs))
	for layer, output := range outputs {
		if layer < 2 {
			if err := source.SetFormat(layer, output.Width, output.Height); err != nil {
				return err
			}
		}
		ceilings[layer] = output.Bitrate
	}
	if err := source.ConfigureOutputs(ceilings); err != nil {
		return err
	}
	for layer := 2; layer < len(outputs); layer++ {
		if err := source.SetFormat(layer, outputs[layer].Width, outputs[layer].Height); err != nil {
			return err
		}
	}
	source.SetLowestLayerRateControlled(true)
	return nil
}

func applyOutputPlan(stream CaptureStream, plan mediaedge.OutputPlan, activeSeen bool) error {
	for layer, bitrate := range plan.Bitrates {
		if bitrate > 0 {
			if err := stream.SetOutputBitrate(layer, bitrate); err != nil {
				return err
			}
		}
	}
	for _, layer := range plan.RecoveryLayers {
		if err := stream.RequestKeyFrame(layer); err != nil {
			return err
		}
	}
	// A new group must receive its budget before activation admits a frame.
	// Startup retains the original until its first active status has arrived.
	if activeSeen {
		for layer, active := range plan.Active {
			if err := stream.SetOutputActive(layer, active); err != nil {
				return err
			}
		}
	}
	return nil
}

func (session *Session) currentStream() CaptureStream {
	session.mu.Lock()
	defer session.mu.Unlock()
	if session.closed {
		return nil
	}
	return session.stream
}

func captureProfileFailure(ctx context.Context, profile nativecapture.VideoProfile, stage string, err error) error {
	slog.DebugContext(ctx, "piik-client", "event", "capture-profile-rejected", "stage", stage,
		"width", profile.Width, "height", profile.Height, "fps", profile.Framerate, "bitrate", profile.Bitrate, diagnostics.Error(err))
	return err
}

func waitForCaptureProfile(
	ctx context.Context,
	stream CaptureStream,
	profile nativecapture.VideoProfile,
	codec string,
	interactive bool,
	allowQuiet bool,
) (CaptureState, error) {
	type result struct {
		state CaptureState
		err   error
		stage string
		input bool
	}
	ready := make(chan result, 1)
	stopped := make(chan struct{})
	defer close(stopped)
	go func() {
		send := func(value result) bool {
			select {
			case ready <- value:
				return true
			case <-stopped:
				return false
			}
		}
		inputSeen := false
		var starting CaptureState
		var unavailable []int
		outputs := stream.Outputs()
		original := min(1, len(outputs)-1)
		for {
			frame, err := stream.Read()
			if err != nil {
				if !errors.Is(err, nativecapture.ErrSourceCanceled) {
					err = errors.New("native capture profile did not become ready")
				}
				send(result{stage: "process-ended", err: err})
				return
			}
			if frame.Kind == nativecapture.FrameLayerUnavailable {
				if starting.State != "starting" || frame.Layer < 0 || frame.Layer >= len(outputs) || frame.Layer == original {
					send(result{stage: "output-unavailable", err: errors.New("native capture profile has an invalid or unavailable original output")})
					return
				}
				if !slices.Contains(unavailable, frame.Layer) {
					unavailable = append(unavailable, frame.Layer)
				}
				continue
			}
			if frame.Kind == nativecapture.FrameBegin && !inputSeen {
				inputSeen = true
				if !send(result{input: true}) {
					return
				}
			}
			if frame.Kind != nativecapture.FrameStatus {
				continue
			}
			state, err := decodeCaptureState(frame.Data)
			if err != nil {
				send(result{stage: "status-invalid", err: err})
				return
			}
			slog.DebugContext(ctx, "piik-client", "event", "capture-profile-observed", "state", state.State,
				"expectedCodec", codec, "actualCodec", state.Codec, "expectedProfile", profile,
				"actualWidth", state.Width, "actualHeight", state.Height, "actualFPS", state.FPS,
				"expectedOutputs", stream.Outputs(), "actualOutputs", state.Outputs)
			if !slices.Equal(state.Outputs, stream.Outputs()) {
				send(result{stage: "outputs-mismatch", err: errors.New("native capture outputs were not applied")})
				return
			}
			if state.Codec != codec {
				send(result{stage: "profile-mismatch", err: errors.New("native capture codec was not applied")})
				return
			}
			if state.State == "active" {
				state.AdapterIndex, state.EncoderIndex = starting.AdapterIndex, starting.EncoderIndex
				state.unavailableLayers = unavailable
				send(result{state: state})
				return
			}
			starting = state
			if !send(result{state: state}) {
				return
			}
		}
	}()
	var timeout <-chan time.Time
	var timer *time.Timer
	if !interactive {
		timer = time.NewTimer(startTimeout)
		timeout = timer.C
		defer timer.Stop()
	}
	inputSeen, startingSeen := false, false
	for {
		select {
		case value := <-ready:
			if value.err != nil {
				return value.state, captureProfileFailure(ctx, profile, value.stage, value.err)
			}
			if value.state.State == "active" {
				return value.state, nil
			}
			if allowQuiet && timer != nil {
				if value.input && !inputSeen {
					if !startingSeen {
						return CaptureState{}, captureProfileFailure(ctx, profile, "status-invalid",
							errors.New("native capture input arrived before its starting state"))
					}
					inputSeen = true
					timer.Reset(startTimeout)
					timeout = timer.C
				} else if value.state.State == "starting" && !inputSeen {
					startingSeen = true
					timer.Stop()
					timeout = nil
				}
			}
		case <-timeout:
			return CaptureState{}, captureProfileFailure(ctx, profile, "wait-timeout",
				errors.New("native capture profile timed out"))
		case <-ctx.Done():
			return CaptureState{}, captureProfileFailure(ctx, profile, "share-stopped",
				errors.New("native share stopped"))
		}
	}
}

func (session *Session) runQuality() {
	ticker := time.NewTicker(qualitySamplePeriod)
	defer ticker.Stop()
	for {
		select {
		case now := <-ticker.C:
			session.mu.Lock()
			edges := make([]*mediaedge.Edge, 0, len(session.edges))
			for _, edge := range session.edges {
				edges = append(edges, edge)
			}
			publications := make(map[publicationKey]*mediaedge.Publication, len(session.publications))
			for key, publication := range session.publications {
				publications[key] = publication
			}
			session.mu.Unlock()
			for _, edge := range edges {
				if sample, ok := edge.QualitySample(now); ok {
					session.emit(Event{
						Type: "edge-quality", ShareID: session.shareID,
						ConnectionID: edge.ConnectionID(), Quality: &sample,
					})
				}
			}
			for key, publication := range publications {
				if sample, ok := publication.QualitySample(now); ok {
					session.emit(Event{Type: "publication-quality", ShareID: session.shareID,
						Current:               func() bool { return session.ownsPublication(key, publication) },
						PublicationGeneration: key.generation, ConnectionID: key.connectionID, PublicationQuality: &sample})
				}
			}
		case <-session.ctx.Done():
			return
		}
	}
}

// Public shares without the microphone opt-in retain their original audio shape.
func (session *Session) runAudio() {
	current := session.currentAudioStream()
	for current != nil {
		frame, err := current.Read()
		if next := session.currentAudioStream(); next != current {
			current = next
			continue
		}
		if err == nil && frame.Kind == nativecapture.FramePCM {
			session.mu.Lock()
			paused := session.paused
			session.mu.Unlock()
			if paused {
				continue
			}
			err = session.audioSource.WritePCM(frame.Data, frame.Duration)
			if err == nil {
				continue
			}
		}
		slog.DebugContext(session.ctx, "piik-client", "event", "capture-audio-stream-ended",
			"share", diagnostics.ID(session.shareID), "frameKind", frame.Kind, "eof", errors.Is(err, io.EOF),
			"canceled", session.ctx.Err() != nil, diagnostics.Error(err))
		// Audio failure leaves video live. Only an explicit source replacement
		// changes this owner; its buffered wake also covers an earlier commit.
		for session.currentAudioStream() == current {
			select {
			case <-session.audioChanged:
			case <-session.ctx.Done():
				return
			}
		}
		current = session.currentAudioStream()
	}
}

func (session *Session) currentAudioStream() CaptureStream {
	session.mu.Lock()
	defer session.mu.Unlock()
	if session.closed {
		return nil
	}
	return session.audioStream
}

func (session *Session) emit(event Event) {
	if session.events == nil {
		return
	}
	if session.ctx.Err() == nil {
		session.events(session.ctx, event)
	}
}

func decodeCaptureState(payload []byte) (CaptureState, error) {
	decoder := json.NewDecoder(bytes.NewReader(payload))
	decoder.DisallowUnknownFields()
	var state CaptureState
	if err := decoder.Decode(&state); err != nil || decoder.Decode(&struct{}{}) != io.EOF ||
		(state.State != "starting" && state.State != "active") ||
		(state.Codec != "h264" && state.Codec != "vp8") ||
		state.HardwareOnly != (state.Codec == "h264") || len(state.Outputs) < 1 || len(state.Outputs) > 6 {
		return CaptureState{}, errors.New("native capture state is invalid")
	}
	for _, output := range state.Outputs {
		if !output.Valid() {
			return CaptureState{}, errors.New("native capture output profile is invalid")
		}
	}
	if state.State == "starting" &&
		(state.AdapterIndex == nil || (state.Codec == "h264" && state.EncoderIndex == nil) ||
			state.AdapterName == "" || state.AdapterIdentity == "" ||
			state.EncoderName == "" || state.EncoderIdentity == "") {
		return CaptureState{}, errors.New("native capture starting state is incomplete")
	}
	original := state.Outputs[min(1, len(state.Outputs)-1)]
	// Output profiles are ceilings; aspect-preserving capture may be smaller.
	if state.State == "active" &&
		((state.Codec == "h264" && !nativecapture.SupportedH264ProfileLevelID(state.ProfileLevelID)) ||
			(state.Codec == "vp8" && state.ProfileLevelID != "") ||
			!nativecapture.ValidVideoSize(state.Width, state.Height) ||
			state.Width > original.Width || state.Height > original.Height ||
			state.FPS != original.Framerate ||
			len(state.RestoreToken) > 4096 || !utf8.ValidString(state.RestoreToken) ||
			strings.ContainsRune(state.RestoreToken, 0)) {
		return CaptureState{}, errors.New("native capture active state is incomplete")
	}
	return state, nil
}

// Selected hardware is a capture fact, not the page's enumeration preference.
// Keep it for quality/source replacement without changing the wire contract.
func (state CaptureState) applyBackend(options *nativecapture.VideoOptions) {
	if state.AdapterIndex != nil {
		options.AdapterIndex = *state.AdapterIndex
	}
	if state.EncoderIndex != nil {
		options.EncoderIndex = *state.EncoderIndex
	}
}

// Optional facts are emitted only to a page which opted into mixed audio.
func (session *Session) SourceAudio() *bool {
	if session.mixer == nil {
		return nil
	}
	session.mixer.mu.Lock()
	defer session.mixer.mu.Unlock()
	available := session.mixer.source != nil
	return &available
}

func (session *Session) SetMicrophone(enabled *bool, gain *float64, deviceID *string) error {
	if enabled != nil || deviceID != nil {
		session.updateMu.Lock()
		defer session.updateMu.Unlock()
	}
	if session.mixer == nil || session.ctx.Err() != nil {
		return errors.New("native microphone is unavailable")
	}
	return session.mixer.setMicrophone(session.capture, enabled, gain, deviceID)
}

func (session *Session) SetVolume(volume float64) error {
	if session.ctx.Err() != nil {
		return session.ctx.Err()
	}
	return session.audioSource.SetVolume(volume)
}