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