Skip to content

capture.md

Latest commit

 

History

History
103 lines (75 loc) · 3.22 KB

capture.md

File metadata and controls

103 lines (75 loc) · 3.22 KB
Raw

Capture one desktop application

Install PocketStation, select one running application, and read its source-aware audio frames. Microphone capture and recording remain off unless you request them.

Prerequisites

  • Python 3.11 or newer;
  • a supported desktop operating system and native capture permissions;
  • one application producing audio.

Install the package:

python -m pip install pocketstation

Capture an application

import pocketstation

with pocketstation.capture(application="Spotify") as live:
    for frame in live.audio:
        print(frame.source_id, frame.stem_id)

Replace Spotify with a display name or application identifier. Pass a positive integer, such as application=1234, when you already have a process ID. Selection must resolve one running application before the Session starts.

A process ID lasts only for that process instance. If the application restarts, discover it again. For a saved selection, use pocketstation.discover_sources() and Source.from_discovered() as described in Persist a source at its supported scope.

The context manager starts one native Session and joins it when the block exits. The iterator receives audio through a native queue that holds 32 frames by default. If Python stops reading and the queue fills, PocketStation drops new frames and reports the loss.

Capture all desktop output

Use Source.system_audio() when the workflow needs every sound playing through the computer. This is an explicit choice because notifications, music, and unrelated applications can be included.

import pocketstation as pks

session = pks.Session()
desktop = session.capture(pks.Source.system_audio())
desktop.send(session.polled_audio())

with session.start() as running:
    for frame in running.audio:
        print(frame.source_id, frame.stem_id)

Use Source.application("Zoom") when the user selected one application and other desktop audio must remain private. Do not open both sources unless the application needs both; their audio can overlap.

Add a microphone or recording

import pocketstation

with pocketstation.capture(
    application="Zoom",
    microphone=True,
    record_to="recordings",
) as live:
    for frame in live.audio:
        print(frame.source_id, frame.stem_id)

Application and microphone frames retain different source and stem identities. Recording writes a separate stem for each selected source.

Use asyncio

import pocketstation.aio as pks

async with pks.capture(application="Spotify") as live:
    async for frame in live.audio:
        print(frame.source_id, frame.stem_id)

The synchronous and asyncio APIs control the same Rust Session. Capture, routing, recording, and Relay remain native; only application and provider work crosses into Python.

Handle setup and delivery failures

Application selection, permission, graph validation, and provider preparation fail before a running Session is returned. During execution, inspect route metrics and discontinuities instead of treating missing frames as silence.

Continue with Session bounds and shutdown or Relay publication.