9d99e50 docs: clarify temporary playback format plumbing · purego-pipewire

M internal/capi/stream_ops.go +3 -0


@@ -87,6 +87,9 @@ func (s *streamOpsImpl) CreatePlaybackStream(loopPtr unsafe.Pointer, name string
87	87
88	88		func (s *streamOpsImpl) ConnectPlaybackStream(streamPtr unsafe.Pointer, format portout.PlaybackFormat) error {
89	89		// Validate format before making the C call.
	90	+	// NOTE: The format fields are not yet forwarded to PipeWire as SPA params.
	91	+	// This validation is a temporary guard that will be superseded once SPA
	92	+	// param building is wired in a subsequent task.
90	93		if format.SampleRate <= 0 \|\| format.Channels <= 0 \|\| format.FramesPerBuffer <= 0 {
91	94		return fmt.Errorf("invalid PlaybackFormat: SampleRate=%d, Channels=%d, FramesPerBuffer=%d",
92	95		format.SampleRate, format.Channels, format.FramesPerBuffer)


@@ -87,6 +87,9 @@ func (s *streamOpsImpl) CreatePlaybackStream(loopPtr unsafe.Pointer, name string
87		87
88	func (s *streamOpsImpl) ConnectPlaybackStream(streamPtr unsafe.Pointer, format portout.PlaybackFormat) error {	88		func (s *streamOpsImpl) ConnectPlaybackStream(streamPtr unsafe.Pointer, format portout.PlaybackFormat) error {
89	// Validate format before making the C call.	89		// Validate format before making the C call.
		90	+	// NOTE: The format fields are not yet forwarded to PipeWire as SPA params.
		91	+	// This validation is a temporary guard that will be superseded once SPA
		92	+	// param building is wired in a subsequent task.
90	if format.SampleRate <= 0 \|\| format.Channels <= 0 \|\| format.FramesPerBuffer <= 0 {	93		if format.SampleRate <= 0 \|\| format.Channels <= 0 \|\| format.FramesPerBuffer <= 0 {
91	return fmt.Errorf("invalid PlaybackFormat: SampleRate=%d, Channels=%d, FramesPerBuffer=%d",	94		return fmt.Errorf("invalid PlaybackFormat: SampleRate=%d, Channels=%d, FramesPerBuffer=%d",
92	format.SampleRate, format.Channels, format.FramesPerBuffer)	95		format.SampleRate, format.Channels, format.FramesPerBuffer)

M internal/capi/stream_ops_test.go +6 -1


@@ -268,7 +268,9 @@ func TestDisconnectStreamReturnsNilOnSuccess(t *testing.T) {
268	268		}
269	269
270	270		// TestConnectPlaybackStreamRejectsMissingFormat verifies that ConnectPlaybackStream
271		-	// now requires a PlaybackFormat and rejects a zero-valued format.
	271	+	// rejects a zero-valued PlaybackFormat at the StreamOps layer. This is a temporary
	272	+	// guard; once SPA params are wired, the rejection will also cover missing/invalid
	273	+	// SPA param construction.
272	274		func TestConnectPlaybackStreamRejectsMissingFormat(t *testing.T) {
273	275		origConnect := pw_stream_connect
274	276		t.Cleanup(func() { pw_stream_connect = origConnect })

@@ -292,6 +294,9 @@ func TestConnectPlaybackStreamRejectsMissingFormat(t *testing.T) {
292	294
293	295		// TestConnectPlaybackStreamBuildsParamsFromFormat verifies that ConnectPlaybackStream
294	296		// accepts a valid PlaybackFormat and calls pw_stream_connect successfully.
	297	+	// NOTE: The format is not yet forwarded to PipeWire as SPA params; this test
	298	+	// only confirms that the format is accepted at the seam. A subsequent task
	299	+	// will add tests verifying that the format values reach the C call.
295	300		func TestConnectPlaybackStreamBuildsParamsFromFormat(t *testing.T) {
296	301		origConnect := pw_stream_connect
297	302		t.Cleanup(func() { pw_stream_connect = origConnect })

 }
 // TestConnectPlaybackStreamRejectsMissingFormat verifies that ConnectPlaybackStream
-// now requires a PlaybackFormat and rejects a zero-valued format.
+// rejects a zero-valued PlaybackFormat at the StreamOps layer. This is a temporary
+// guard; once SPA params are wired, the rejection will also cover missing/invalid
+// SPA param construction.
 func TestConnectPlaybackStreamRejectsMissingFormat(t *testing.T) {
 	origConnect := pw_stream_connect
 	t.Cleanup(func() { pw_stream_connect = origConnect })
 // TestConnectPlaybackStreamBuildsParamsFromFormat verifies that ConnectPlaybackStream
 // accepts a valid PlaybackFormat and calls pw_stream_connect successfully.
+// NOTE: The format is not yet forwarded to PipeWire as SPA params; this test
+// only confirms that the format is accepted at the seam. A subsequent task
+// will add tests verifying that the format values reach the C call.
 func TestConnectPlaybackStreamBuildsParamsFromFormat(t *testing.T) {
 	origConnect := pw_stream_connect
 	t.Cleanup(func() { pw_stream_connect = origConnect })

M internal/core/player_rt.go +3 -0


@@ -36,6 +36,9 @@ func (b *PCMBuffer) allocate() {
36	36
37	37		// PlayerConfig holds configuration for the player
38	38		type PlayerConfig struct {
	39	+	// SampleRate is carried here for upcoming runtime format negotiation.
	40	+	// It is not yet consumed by the core player but will be used when the
	41	+	// StreamOps layer builds SPA params for PipeWire.
39	42		SampleRate int
40	43		FramesPerBuffer int
41	44		Channels int


@@ -36,6 +36,9 @@ func (b *PCMBuffer) allocate() {
36		36
37	// PlayerConfig holds configuration for the player	37		// PlayerConfig holds configuration for the player
38	type PlayerConfig struct {	38		type PlayerConfig struct {
		39	+	// SampleRate is carried here for upcoming runtime format negotiation.
		40	+	// It is not yet consumed by the core player but will be used when the
		41	+	// StreamOps layer builds SPA params for PipeWire.
39	SampleRate int	42		SampleRate int
40	FramesPerBuffer int	43		FramesPerBuffer int
41	Channels int	44		Channels int

M internal/ports/out/stream_ops.go +6 -1


@@ -3,6 +3,10 @@ package out
3	3		import "unsafe"
4	4
5	5		// PlaybackFormat describes the audio format for a playback stream.
	6	+	// The fields are carried through the public API and core config now so the
	7	+	// plumbing is in place for upcoming runtime format negotiation. The values
	8	+	// are not yet forwarded to PipeWire; that will happen when SPA param
	9	+	// building is wired in a subsequent task.
6	10		type PlaybackFormat struct {
7	11		SampleRate int
8	12		Channels int

@@ -19,7 +23,8 @@ type StreamOps interface {
19	23		CreatePlaybackStream(loopPtr unsafe.Pointer, name string, onProcess func()) (streamPtr unsafe.Pointer, err error)
20	24
21	25		// ConnectPlaybackStream connects the stream for playback output using the
22		-	// given format. Returns an error if the format is invalid or the C call fails.
	26	+	// given format. The format is currently validated but not yet forwarded to
	27	+	// PipeWire as SPA params; that wiring will happen in a subsequent task.
23	28		ConnectPlaybackStream(streamPtr unsafe.Pointer, format PlaybackFormat) error
24	29
25	30		// SetStreamActive activates or deactivates the stream.

 import "unsafe"
 // PlaybackFormat describes the audio format for a playback stream.
+// The fields are carried through the public API and core config now so the
+// plumbing is in place for upcoming runtime format negotiation.  The values
+// are not yet forwarded to PipeWire; that will happen when SPA param
+// building is wired in a subsequent task.
 type PlaybackFormat struct {
 	SampleRate      int
 	Channels        int
 	CreatePlaybackStream(loopPtr unsafe.Pointer, name string, onProcess func()) (streamPtr unsafe.Pointer, err error)
 	// ConnectPlaybackStream connects the stream for playback output using the
-	// given format. Returns an error if the format is invalid or the C call fails.
+	// given format. The format is currently validated but not yet forwarded to
+	// PipeWire as SPA params; that wiring will happen in a subsequent task.
 	ConnectPlaybackStream(streamPtr unsafe.Pointer, format PlaybackFormat) error
 	// SetStreamActive activates or deactivates the stream.