Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
package nativecapture
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"log/slog"
"os"
"os/exec"
"regexp"
"strconv"
"strings"
"sync"
"time"
"unicode/utf8"
"github.com/TNTcraftHIM/Piik/internal/diagnostics"
)
const (
captureStopTimeout = time.Second
maxPreviewBytes = 192 * 1024
maxOutputs = 6
MaxOutputGroups = maxOutputs - 2
minOutputBitrate = 1_000 // Codec rate APIs use whole kbps.
MaxVideoBitrate = 240_000_000 // H.264 Level 5.2 Constrained Baseline video bitrate.
maxSources = 1024
maxSourceTitleBytes = 4096
// Leave room for the control envelope within loopback's 256 KiB message.
maxSourceListBytes = 192 * 1024
// A complete helper list may be larger than the returned prefix. Decode it
// incrementally; JSON escaping can use six bytes for each title byte.
maxSourceOutputBytes = maxSources*(maxSourceTitleBytes*6+256) + 2
)
var (
captureStageCode = regexp.MustCompile(`^[a-z][a-z0-9-]{0,63}$`)
captureHRESULT = regexp.MustCompile(`^0x[0-9a-fA-F]{8}$`)
)
// Failure contains only validated helper codes, never stderr detail or identity.
type Failure struct {
Stage string `json:"stage,omitempty"`
HRESULT string `json:"hresult,omitempty"`
ExitCode int `json:"exitCode"`
}
type processFailure struct {
details Failure
cause error
}
func (failure *processFailure) Error() string {
return fmt.Sprintf("native capture failed (stage=%s, hresult=%s): %v", failure.details.Stage, failure.details.HRESULT, failure.cause)
}
func (failure *processFailure) Unwrap() error { return failure.cause }
func FailureDetails(err error) *Failure {
var failure *processFailure
if !errors.As(err, &failure) {
return nil
}
details := failure.details
return &details
}
type audioCaptureState struct {
State string `json:"state"`
Audio bool `json:"audio"`
}
type CaptureTarget struct {
Kind string `json:"kind"`
SourceID string `json:"sourceId"`
PID uint32 `json:"pid,omitempty"`
CreationTime string `json:"creationTime,omitempty"`
Title string `json:"title"`
}
type VideoOptions struct {
RemoteInput bool
Target CaptureTarget
Codec string
AdapterIndex uint32
EncoderIndex uint32
Profile VideoProfile
RestoreToken string
OutputGroups int
ShowCaptureBorder bool
}
type EncodedVideoOptions struct {
Codec string
AdapterIndex uint32
EncoderIndex uint32
Preference string
Outputs []OutputProfile
}
type VideoProfile struct {
Width uint32
Height uint32
Framerate uint32
Bitrate uint32
Preference string
}
// OutputProfile describes one codec output, not a selectable product preset.
type OutputProfile struct {
Width uint32 `json:"width"`
Height uint32 `json:"height"`
Framerate uint32 `json:"fps"`
Bitrate uint32 `json:"bitrate"`
}
func (profile OutputProfile) Valid() bool {
return ValidVideoFormat(profile.Width, profile.Height, profile.Framerate) &&
profile.Bitrate >= minOutputBitrate && profile.Bitrate <= MaxVideoBitrate
}
// ScreenShareOutputs follows LiveKit 2.22.1's screen-share simulcast construction,
// with even derived dimensions for NV12. The source profile has already passed Valid.
func ScreenShareOutputs(profile VideoProfile) []OutputProfile {
return []OutputProfile{
{
Width: profile.Width / 4 * 2, Height: profile.Height / 4 * 2,
Framerate: profile.Framerate, Bitrate: min(profile.Bitrate, max(150_000, profile.Bitrate/4)),
},
{
Width: profile.Width, Height: profile.Height,
Framerate: profile.Framerate, Bitrate: profile.Bitrate,
},
}
}
func (profile VideoProfile) Valid() bool {
// The source ceiling must also yield a valid half-size output. Preset labels
// belong to the UI, not the capture process's numeric resource boundary.
return ValidVideoFormat(profile.Width, profile.Height, profile.Framerate) && profile.Width >= 4 && profile.Height >= 4 &&
profile.Bitrate >= 100_000 && profile.Bitrate <= MaxVideoBitrate &&
validVideoPreference(profile.Preference)
}
func validVideoPreference(preference string) bool {
return preference == "maintain-resolution" || preference == "balanced" || preference == "maintain-framerate"
}
type Stream struct {
remoteInput bool
cancel context.CancelFunc
input io.ReadCloser
key io.WriteCloser
done chan error
outputs []OutputProfile
active [maxOutputs]bool
bitrates [maxOutputs]uint32
controlMu sync.Mutex
closed bool
closeOnce sync.Once
failure error // Published before done; read only after process retirement.
readMu sync.Mutex
readEnd sync.Once
logger *slog.Logger
ctx context.Context
}
func ListSources(parent context.Context, executable string) ([]CaptureTarget, error) {
ctx, cancel := context.WithTimeout(parent, probeTimeout)
defer cancel()
command := exec.CommandContext(ctx, executable, "--list")
stderr := diagnostics.Writer("native-source-list")
defer stderr.Close()
command.Stderr = stderr
hideWindow(command)
stdout, err := command.StdoutPipe()
if err != nil {
return nil, errors.New("native capture source list is unavailable")
}
if err := command.Start(); err != nil {
slog.DebugContext(ctx, "piik-client", "event", "capture-source-list-failed", diagnostics.Error(err), "canceled", ctx.Err() != nil)
return nil, errors.New("native capture source list is unavailable")
}
targets, readErr := readSources(stdout)
if readErr != nil {
cancel()
}
waitErr := command.Wait()
if waitErr != nil {
slog.DebugContext(ctx, "piik-client", "event", "capture-source-list-failed", diagnostics.Error(waitErr), "canceled", ctx.Err() != nil)
}
if readErr != nil {
return nil, errors.New("native capture source list is invalid")
}
if waitErr != nil {
return nil, errors.New("native capture source list is unavailable")
}
return targets, nil
}
func readSources(reader io.Reader) ([]CaptureTarget, error) {
input := &io.LimitedReader{R: reader, N: maxSourceOutputBytes + 1}
decoder := json.NewDecoder(input)
decoder.DisallowUnknownFields()
invalid := errors.New("native capture source list is invalid")
if token, err := decoder.Token(); err != nil || token != json.Delim('[') {
return nil, invalid
}
targets := make([]CaptureTarget, 0)
size := 2 // JSON array delimiters; subsequent entries also need a comma.
full := false
for count := 0; decoder.More(); count++ {
var target CaptureTarget
if count >= maxSources || decoder.Decode(&target) != nil || !target.Valid() {
return nil, invalid
}
if full {
continue
}
encoded, err := json.Marshal(target)
if err != nil {
return nil, invalid
}
if size+len(encoded)+1 > maxSourceListBytes {
full = true
continue
}
targets = append(targets, target)
size += len(encoded) + 1
}
if token, err := decoder.Token(); err != nil || token != json.Delim(']') {
return nil, invalid
}
if decoder.Decode(&struct{}{}) != io.EOF || input.N == 0 {
return nil, invalid
}
return targets, nil
}
func PreviewSource(parent context.Context, executable string, target CaptureTarget) ([]byte, error) {
if !target.Valid() {
return nil, errors.New("native preview target is invalid")
}
ctx, cancel := context.WithTimeout(parent, probeTimeout)
defer cancel()
stdout := &boundedBuffer{limit: maxPreviewBytes}
command := exec.CommandContext(ctx, executable,
"--preview",
target.Kind,
target.SourceID,
strconv.FormatUint(uint64(target.PID), 10),
zeroWhenEmpty(target.CreationTime),
)
command.Stdout = stdout
stderr := diagnostics.Writer("native-source-preview")
defer stderr.Close()
command.Stderr = stderr
hideWindow(command)
if err := command.Run(); err != nil {
slog.DebugContext(ctx, "piik-client", "event", "capture-source-preview-failed", diagnostics.Error(err), "canceled", ctx.Err() != nil)
return nil, errors.New("native capture preview is unavailable")
}
preview := stdout.Bytes()
if len(preview) < 54 || preview[0] != 'B' || preview[1] != 'M' {
return nil, errors.New("native capture preview is invalid")
}
return append([]byte(nil), preview...), nil
}
func StartVideo(parent context.Context, executable string, options VideoOptions) (*Stream, error) {
if !options.Target.Valid() || !options.Profile.Valid() ||
(options.Codec != "auto" && options.Codec != "h264" && options.Codec != "vp8") ||
options.OutputGroups < 0 || options.OutputGroups > MaxOutputGroups ||
len(options.RestoreToken) > 4096 || !utf8.ValidString(options.RestoreToken) ||
strings.ContainsRune(options.RestoreToken, 0) {
return nil, errors.New("native video target is invalid")
}
environment := []string(nil)
if options.RestoreToken != "" {
environment = []string{"PIIK_XDP_RESTORE_TOKEN=" + options.RestoreToken}
}
if options.RemoteInput {
environment = append(environment, "PIIK_CAPTURE_REMOTE_INPUT=1")
}
arguments := []string{
"--capture-video",
options.Target.Kind,
options.Target.SourceID,
strconv.FormatUint(uint64(options.Target.PID), 10),
zeroWhenEmpty(options.Target.CreationTime),
"--adapter-index",
strconv.FormatUint(uint64(options.AdapterIndex), 10),
"--mft-index",
strconv.FormatUint(uint64(options.EncoderIndex), 10),
"--width",
strconv.FormatUint(uint64(options.Profile.Width), 10),
"--height",
strconv.FormatUint(uint64(options.Profile.Height), 10),
"--fps",
strconv.FormatUint(uint64(options.Profile.Framerate), 10),
"--bitrate",
strconv.FormatUint(uint64(options.Profile.Bitrate), 10),
"--preference",
options.Profile.Preference,
"--codec",
options.Codec,
"--protocol-v7",
}
outputs := ScreenShareOutputs(options.Profile)
for range options.OutputGroups {
outputs = append(outputs, outputs[0])
}
arguments, err := appendOutputArguments(arguments, outputs)
if err != nil {
return nil, err
}
if options.ShowCaptureBorder {
arguments = append(arguments, "--show-capture-border")
}
stream, err := startStreamWithEnvironment(parent, executable, arguments, environment)
if err != nil {
return nil, err
}
stream.outputs = outputs
stream.remoteInput = options.RemoteInput
stream.active[0], stream.active[1] = true, true
return stream, nil
}
func StartEncodedVideo(parent context.Context, executable string, options EncodedVideoOptions) (*Stream, error) {
if (options.Codec != "h264" && options.Codec != "vp8") || !validVideoPreference(options.Preference) {
return nil, errors.New("native encoded video options are invalid")
}
arguments, err := appendOutputArguments([]string{
"--encoded-video", "--codec", options.Codec,
"--adapter-index", strconv.FormatUint(uint64(options.AdapterIndex), 10),
"--mft-index", strconv.FormatUint(uint64(options.EncoderIndex), 10),
"--preference", options.Preference, "--protocol-v7",
}, options.Outputs)
if err != nil {
return nil, err
}
stream, err := startStream(parent, executable, arguments)
if err != nil {
return nil, err
}
stream.outputs = append([]OutputProfile(nil), options.Outputs...)
return stream, nil
}
func appendOutputArguments(arguments []string, outputs []OutputProfile) ([]string, error) {
if len(outputs) < 1 || len(outputs) > maxOutputs {
return nil, errors.New("native output count is invalid")
}
for _, output := range outputs {
if !output.Valid() {
return nil, errors.New("native output profile is invalid")
}
arguments = append(arguments, "--output", strconv.FormatUint(uint64(output.Width), 10),
strconv.FormatUint(uint64(output.Height), 10), strconv.FormatUint(uint64(output.Framerate), 10), strconv.FormatUint(uint64(output.Bitrate), 10))
}
return arguments, nil
}
func StartAudio(parent context.Context, executable string, target CaptureTarget, exclude bool) (*Stream, error) {
if !target.Valid() || (exclude && target.Kind != "window") {
return nil, errors.New("native audio target is invalid")
}
kind := target.Kind
if exclude {
kind = "exclude"
}
return startAudioStream(parent, executable, []string{
"--capture-audio",
kind,
strconv.FormatUint(uint64(target.PID), 10),
zeroWhenEmpty(target.CreationTime),
})
}
func StartSystemAudio(parent context.Context, executable string) (*Stream, error) {
return startAudioStream(parent, executable, []string{
"--capture-audio", "display", "0", "0",
})
}
func StartMicrophone(parent context.Context, executable, deviceID string) (*Stream, error) {
if !ValidDeviceID(deviceID) {
return nil, errors.New("microphone device is invalid")
}
arguments := []string{"--capture-microphone"}
if deviceID != "" {
arguments = append(arguments, "--device", deviceID)
}
return startAudioStreamWithTimeout(parent, executable, arguments, time.Minute)
}
func startAudioStream(parent context.Context, executable string, arguments []string) (*Stream, error) {
return startAudioStreamWithTimeout(parent, executable, arguments, probeTimeout)
}
func startAudioStreamWithTimeout(parent context.Context, executable string, arguments []string, timeout time.Duration) (*Stream, error) {
if parent == nil {
parent = context.Background()
}
stream, err := startStream(parent, executable, arguments)
if err != nil {
return nil, err
}
ready := make(chan error, 1)
go func() {
frame, readErr := stream.Read()
if readErr != nil {
ready <- errors.New("native audio capture did not become ready")
return
}
ready <- validateAudioReadyFrame(frame)
}()
timer := time.NewTimer(timeout)
defer timer.Stop()
select {
case readyErr := <-ready:
if readyErr == nil {
return stream, nil
}
_ = stream.Close()
return nil, readyErr
case <-timer.C:
_ = stream.Close()
return nil, errors.New("native audio capture timed out during startup")
case <-parent.Done():
_ = stream.Close()
return nil, parent.Err()
}
}
func (target CaptureTarget) Valid() bool {
if !positiveDecimal(target.SourceID) || len(target.Title) == 0 ||
len(target.Title) > maxSourceTitleBytes {
return false
}
switch target.Kind {
case "window":
return target.PID > 0 && positiveDecimal(target.CreationTime)
case "display":
return target.PID == 0 && target.CreationTime == ""
case "picker":
return target.PID == 0 && target.CreationTime == ""
default:
return false
}
}
func zeroWhenEmpty(value string) string {
if value == "" {
return "0"
}
return value
}
func validateAudioReadyFrame(frame Frame) error {
var state audioCaptureState
if frame.Kind != FrameStatus || decodeStrictJSON(frame.Data, &state) != nil ||
state.State != "active" || !state.Audio {
return errors.New("native audio capture returned an invalid ready state")
}
return nil
}
func positiveDecimal(value string) bool {
if value == "" || len(value) > 20 || value[0] == '0' {
return false
}
for _, character := range value {
if character < '0' || character > '9' {
return false
}
}
_, err := strconv.ParseUint(value, 10, 64)
return err == nil
}
func startStream(parent context.Context, executable string, arguments []string) (*Stream, error) {
return startStreamWithEnvironment(parent, executable, arguments, nil)
}
func startStreamWithEnvironment(
parent context.Context,
executable string,
arguments []string,
environment []string,
) (*Stream, error) {
if parent == nil {
parent = context.Background()
}
if executable == "" {
return nil, errors.New("native capture process is unavailable")
}
if err := parent.Err(); err != nil {
return nil, err
}
// Parent cancellation requests the same bounded Q/Close sequence as an
// explicit stop. Killing first can leave platform capture state behind.
ctx, cancel := context.WithCancel(context.WithoutCancel(parent))
started := time.Now()
// A diagnostic-only process label correlates stderr while old/new captures overlap.
captureID := strconv.FormatInt(started.UnixNano(), 36)
logger := slog.Default().With("capture", captureID)
command := exec.CommandContext(ctx, executable, arguments...)
if logger.Enabled(ctx, slog.LevelDebug) {
environment = append(environment, "PIIK_CAPTURE_DEBUG=1")
}
if len(environment) > 0 {
command.Env = append(os.Environ(), environment...)
}
stdout, err := command.StdoutPipe()
if err != nil {
cancel()
return nil, err
}
stdin, err := command.StdinPipe()
if err != nil {
cancel()
return nil, err
}
stderr := &boundedBuffer{limit: maxProbeErrorBytes, discardOverflow: true}
trace := diagnostics.Writer("native-capture/" + captureID)
command.Stderr = io.MultiWriter(stderr, trace)
hideWindow(command)
if err = command.Start(); err != nil {
_ = trace.Close()
cancel()
logger.DebugContext(ctx, "piik-client", "event", "capture-process-start-failed", diagnostics.Error(err))
return nil, fmt.Errorf("start native capture process: %w", err)
}
logger = logger.With("pid", command.Process.Pid)
mode := "capture"
if len(arguments) > 0 {
switch arguments[0] {
case "--capture-video", "--capture-audio", "--encoded-video":
mode = strings.TrimPrefix(arguments[0], "--")
}
}
logger.DebugContext(ctx, "piik-client", "event", "capture-process-started", "mode", mode)
stream := &Stream{
cancel: cancel,
input: stdout,
key: stdin,
done: make(chan error, 1),
logger: logger,
ctx: ctx,
}
stopParent := context.AfterFunc(parent, func() { _ = stream.Close() })
go func() {
waitErr := command.Wait()
stopParent()
_ = trace.Close()
stage, hresult := captureFailureCodes(stderr.Bytes())
if waitErr != nil && (stage != "" || hresult != "" || ctx.Err() == nil) {
// Preserve validated failure codes and the exit cause for diagnostics
// and errors.Is/As, never the helper's raw detail.
stream.failure = &processFailure{details: Failure{Stage: stage, HRESULT: hresult, ExitCode: command.ProcessState.ExitCode()}, cause: waitErr}
}
logCaptureFailure(ctx, waitErr, command.ProcessState.ExitCode(), stderr.Bytes())
logger.DebugContext(ctx, "piik-client", "event", "capture-process-ended", "mode", mode,
"durationMs", time.Since(started).Milliseconds(), "exitCode", command.ProcessState.ExitCode(),
"canceled", ctx.Err() != nil, "cancelReason", diagnostics.SafeText(fmt.Sprint(context.Cause(ctx))), diagnostics.Error(waitErr))
stream.done <- waitErr
close(stream.done)
}()
return stream, nil
}
func logCaptureFailure(ctx context.Context, err error, exitCode int, stderr []byte) {
if err == nil || !slog.Default().Enabled(ctx, slog.LevelDebug) {
return
}
stage, hresult := captureFailureCodes(stderr)
canceled := ctx.Err() != nil
// A real child failure may race owner cancellation. Keep its fixed codes,
// while ordinary cancellation without a reported failure stays silent.
if canceled && stage == "" && hresult == "" {
return
}
slog.DebugContext(ctx, "piik-client", "event", "capture-process-failed",
"exitCode", exitCode, "stage", stage, "hresult", hresult, "canceled", canceled)
}
func captureFailureCodes(stderr []byte) (stage, hresult string) {
for _, line := range strings.Split(string(stderr), "\n") {
key, value, _ := strings.Cut(strings.TrimSuffix(line, "\r"), "=")
switch {
case key == "stage" && stage == "" && captureStageCode.MatchString(value):
stage = value
case key == "hresult" && hresult == "" && captureHRESULT.MatchString(value):
hresult = strings.ToLower(value)
}
}
return
}
func (stream *Stream) Read() (Frame, error) {
stream.readMu.Lock()
frame, err := readFrame(stream.input)
stream.readMu.Unlock()
if err != nil && stream.logger != nil {
stream.readEnd.Do(func() {
stream.logger.DebugContext(stream.ctx, "piik-client", "event", "capture-stream-ended",
"eof", errors.Is(err, io.EOF), "canceled", stream.ctx.Err() != nil, diagnostics.Error(err))
})
}
return frame, err
}
// WriteFrame shares the existing stdin lock with control. Only encoded video
// crosses this input boundary; capture status and PCM remain producer outputs.
func (stream *Stream) WriteFrame(frame Frame) error {
if frame.Kind != FrameH264 && frame.Kind != FrameVP8 {
return errors.New("native encoded input is not video")
}
stream.controlMu.Lock()
defer stream.controlMu.Unlock()
if stream.closed {
return io.ErrClosedPipe
}
return writeFrame(stream.key, frame)
}
func (stream *Stream) Outputs() []OutputProfile {
return append([]OutputProfile(nil), stream.outputs...)
}
func (stream *Stream) RequestKeyFrame(layer int) error {
if layer < -1 || layer >= len(stream.outputs) || len(stream.outputs) == 0 {
return errors.New("native recovery output is invalid")
}
return stream.writeControl("K " + strconv.Itoa(layer))
}
func (stream *Stream) SetOutputActive(layer int, active bool) error {
if layer < 0 || layer >= len(stream.outputs) {
return errors.New("native active output is invalid")
}
stream.controlMu.Lock()
defer stream.controlMu.Unlock()
if stream.closed {
return io.ErrClosedPipe
}
if stream.active[layer] == active {
return nil
}
value := "0"
if active {
value = "1"
}
if err := stream.writeControlLocked("A " + strconv.Itoa(layer) + " " + value); err != nil {
return err
}
stream.active[layer] = active
return nil
}
func (stream *Stream) SetOutputBitrate(layer int, bitrate uint32) error {
if layer < 0 || layer >= len(stream.outputs) || bitrate < minOutputBitrate || bitrate > stream.outputs[layer].Bitrate {
return errors.New("native output bitrate is invalid")
}
stream.controlMu.Lock()
defer stream.controlMu.Unlock()
if stream.closed {
return io.ErrClosedPipe
}
if stream.bitrates[layer] == bitrate {
return nil
}
if err := stream.writeControlLocked("B " + strconv.Itoa(layer) + " " + strconv.FormatUint(uint64(bitrate), 10)); err != nil {
return err
}
stream.bitrates[layer] = bitrate
return nil
}
func (stream *Stream) writeControl(command string) error {
stream.controlMu.Lock()
defer stream.controlMu.Unlock()
return stream.writeControlLocked(command)
}
// Remote input uses the selected Portal capture's inherited control pipe; it
// never opens a separate OS session, listener or network route.
func (stream *Stream) RemoteInput() bool {
// Availability cannot wait behind a blocked media-control write: the input
// owner must remain able to reach its bounded write/retirement path.
return stream != nil && stream.remoteInput && stream.ctx.Err() == nil
}
func (stream *Stream) SendRemoteInput(command string) error {
if stream == nil {
return errors.New("capture input is unavailable")
}
// A stalled helper must not hold the input grant lock indefinitely. Retire
// that same capture if even a small control command cannot make progress.
timer := time.AfterFunc(captureStopTimeout, stream.cancel)
defer timer.Stop()
if !stream.RemoteInput() {
return errors.New("capture input is unavailable")
}
err := stream.writeControl("I " + command)
if err != nil {
stream.cancel()
}
return err
}
func (stream *Stream) writeControlLocked(command string) error {
if stream.closed {
return io.ErrClosedPipe
}
return writeFrame(stream.key, Frame{Kind: FrameControl, Data: []byte(command)})
}
func (stream *Stream) Done() <-chan error {
return stream.done
}
func (stream *Stream) Close() error {
stream.closeOnce.Do(func() {
// Start the stop budget before waiting for a possibly blocked control write.
timer := time.AfterFunc(captureStopTimeout, stream.cancel)
defer timer.Stop()
// A retired consumer must not leave the producer blocked on stdout before
// it can read Q. Finish any in-flight frame before discarding the rest.
drained := make(chan struct{})
go func() {
stream.readMu.Lock()
_, _ = io.Copy(io.Discard, stream.input)
stream.readMu.Unlock()
close(drained)
}()
stream.controlMu.Lock()
stream.closed = true
_ = writeFrame(stream.key, Frame{Kind: FrameControl, Data: []byte("Q")})
_ = stream.key.Close()
stream.controlMu.Unlock()
<-stream.done
stream.cancel()
<-drained
})
return stream.failure
}