From cedebdc8362210556e34057c7d142d0a44a8e6d8 Mon Sep 17 00:00:00 2001 From: tosscaster Date: Sun, 12 Jul 2026 10:19:50 +0900 Subject: [PATCH 1/3] feat(appsink): expose buffer pts/dts on pulled samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `gst_sample_to_js` already has the sample's `GstBuffer` in hand but only surfaces `buffer`, `flags` and `caps` — not the timing. So `onSample`/`getSample` consumers that need a frame's PTS have to add a separate pad probe and re-pair it with the sample by FIFO order, which is not 1:1 under drops/reorder. Extract `GST_BUFFER_PTS`/`GST_BUFFER_DTS` (nanoseconds, omitted when invalid) onto the returned sample object, mirroring the existing pad-probe path. Adds `pts?`/`dts?` to the `GStreamerSample` type and a test asserting consecutive 30fps PTS deltas. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/cpp/type-conversion.cpp | 10 ++++++++++ src/ts/appsink.test.ts | 22 ++++++++++++++++++++++ src/ts/index.ts | 5 +++++ 3 files changed, 37 insertions(+) diff --git a/src/cpp/type-conversion.cpp b/src/cpp/type-conversion.cpp index 165031e..433ff3f 100644 --- a/src/cpp/type-conversion.cpp +++ b/src/cpp/type-conversion.cpp @@ -410,6 +410,16 @@ namespace TypeConversion { // Add flags from buffer GstBufferFlags flags = gst_buffer_get_flags(buf); result.Set("flags", Napi::Number::New(env, static_cast(flags))); + + // Add timing information from buffer (nanoseconds; omitted when invalid). This lets + // onSample/getSample consumers read a frame's PTS atomically with its buffer instead of + // adding a separate pad probe (which is not 1:1 with the sample under drops/reorder). + if (GST_BUFFER_PTS_IS_VALID(buf)) { + result.Set("pts", Napi::Number::New(env, static_cast(GST_BUFFER_PTS(buf)))); + } + if (GST_BUFFER_DTS_IS_VALID(buf)) { + result.Set("dts", Napi::Number::New(env, static_cast(GST_BUFFER_DTS(buf)))); + } } // Add caps from sample diff --git a/src/ts/appsink.test.ts b/src/ts/appsink.test.ts index 1ca8f88..a6259ef 100644 --- a/src/ts/appsink.test.ts +++ b/src/ts/appsink.test.ts @@ -107,4 +107,26 @@ describe("AppSink", () => { expect(samples).toHaveLength(frames); expect(samples[0].buffer).toBeDefined(); }); + + it("should expose the buffer pts on pulled samples", async () => { + const pipeline = new Pipeline( + "videotestsrc num-buffers=5 is-live=false ! video/x-raw,framerate=30/1 " + + "! videoconvert ! appsink name=sink" + ); + const sink = pipeline.getElementByName("sink"); + + if (sink?.type !== "app-sink-element") throw new Error("Expected app sink element"); + + await pipeline.play(); + + const first = await sink.getSample(); + const second = await sink.getSample(); + + await pipeline.stop(); + + expect(typeof first?.pts).toBe("number"); + expect(typeof second?.pts).toBe("number"); + // videotestsrc timestamps buffers by running time: at 30fps consecutive PTS differ by 1/30s. + expect((second!.pts as number) - (first!.pts as number)).toBe(33_333_333); + }); }); diff --git a/src/ts/index.ts b/src/ts/index.ts index 5a1ab33..4cb1572 100644 --- a/src/ts/index.ts +++ b/src/ts/index.ts @@ -17,6 +17,11 @@ export type GStreamerPropertyValue = // Sample object returned for GST_VALUE_HOLDS_SAMPLE properties export type GStreamerSample = { buffer?: Buffer; + + // Timing information from the sample's buffer (omitted when the buffer has no valid value) + pts?: number; // Presentation timestamp (nanoseconds) + dts?: number; // Decode timestamp (nanoseconds) + flags?: number; caps?: { name?: string; From 209d938c59c4bcb231e5861ec8948c5cd8a70856 Mon Sep 17 00:00:00 2001 From: Tosscaster Date: Tue, 21 Jul 2026 17:26:37 +0900 Subject: [PATCH 2/3] feat(appsink): also expose duration/offset/offsetEnd on samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback: the previous commit said it mirrored the pad-probe path but only carried `pts`/`dts`, while `BufferData` also exposes `duration`, `offset` and `offsetEnd`. Add the missing three, guarded the same way, so both paths surface the same buffer metadata instead of leaving an asymmetry behind. Also trim the code comment down to what it describes — the reason this beats a separate pad probe belongs in the PR description, not in the source. The appsink test now covers the frame duration and consecutive frame offsets as well. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/cpp/type-conversion.cpp | 16 +++++++++++++--- src/ts/appsink.test.ts | 5 ++++- src/ts/index.ts | 6 +++++- 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/src/cpp/type-conversion.cpp b/src/cpp/type-conversion.cpp index 433ff3f..0781f5f 100644 --- a/src/cpp/type-conversion.cpp +++ b/src/cpp/type-conversion.cpp @@ -411,15 +411,25 @@ namespace TypeConversion { GstBufferFlags flags = gst_buffer_get_flags(buf); result.Set("flags", Napi::Number::New(env, static_cast(flags))); - // Add timing information from buffer (nanoseconds; omitted when invalid). This lets - // onSample/getSample consumers read a frame's PTS atomically with its buffer instead of - // adding a separate pad probe (which is not 1:1 with the sample under drops/reorder). + // Add timing and offset information from buffer (pts/dts/duration in nanoseconds). + // Each field is omitted when the buffer holds no valid value for it. if (GST_BUFFER_PTS_IS_VALID(buf)) { result.Set("pts", Napi::Number::New(env, static_cast(GST_BUFFER_PTS(buf)))); } if (GST_BUFFER_DTS_IS_VALID(buf)) { result.Set("dts", Napi::Number::New(env, static_cast(GST_BUFFER_DTS(buf)))); } + if (GST_BUFFER_DURATION_IS_VALID(buf)) { + result.Set("duration", + Napi::Number::New(env, static_cast(GST_BUFFER_DURATION(buf)))); + } + if (GST_BUFFER_OFFSET_IS_VALID(buf)) { + result.Set("offset", Napi::Number::New(env, static_cast(GST_BUFFER_OFFSET(buf)))); + } + if (GST_BUFFER_OFFSET_END_IS_VALID(buf)) { + result.Set("offsetEnd", + Napi::Number::New(env, static_cast(GST_BUFFER_OFFSET_END(buf)))); + } } // Add caps from sample diff --git a/src/ts/appsink.test.ts b/src/ts/appsink.test.ts index a6259ef..cc54f23 100644 --- a/src/ts/appsink.test.ts +++ b/src/ts/appsink.test.ts @@ -108,7 +108,7 @@ describe("AppSink", () => { expect(samples[0].buffer).toBeDefined(); }); - it("should expose the buffer pts on pulled samples", async () => { + it("should expose the buffer timing metadata on pulled samples", async () => { const pipeline = new Pipeline( "videotestsrc num-buffers=5 is-live=false ! video/x-raw,framerate=30/1 " + "! videoconvert ! appsink name=sink" @@ -128,5 +128,8 @@ describe("AppSink", () => { expect(typeof second?.pts).toBe("number"); // videotestsrc timestamps buffers by running time: at 30fps consecutive PTS differ by 1/30s. expect((second!.pts as number) - (first!.pts as number)).toBe(33_333_333); + // Same source stamps each buffer with the frame duration and its frame offsets. + expect(first?.duration).toBe(33_333_333); + expect(second!.offset as number).toBe((first!.offset as number) + 1); }); }); diff --git a/src/ts/index.ts b/src/ts/index.ts index 4cb1572..c9c594b 100644 --- a/src/ts/index.ts +++ b/src/ts/index.ts @@ -18,9 +18,13 @@ export type GStreamerPropertyValue = export type GStreamerSample = { buffer?: Buffer; - // Timing information from the sample's buffer (omitted when the buffer has no valid value) + // Timing and offset information from the sample's buffer (omitted when the buffer has no + // valid value for that field) pts?: number; // Presentation timestamp (nanoseconds) dts?: number; // Decode timestamp (nanoseconds) + duration?: number; // Buffer duration (nanoseconds) + offset?: number; // Media-specific start offset + offsetEnd?: number; // Media-specific end offset flags?: number; caps?: { From 25408733d899039d849641b27c77f7bda1ed320c Mon Sep 17 00:00:00 2001 From: Serhii Mamedov Date: Fri, 31 Jul 2026 14:00:23 +0300 Subject: [PATCH 3/3] Apply formatting --- src/cpp/type-conversion.cpp | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/cpp/type-conversion.cpp b/src/cpp/type-conversion.cpp index 0781f5f..093a2ab 100644 --- a/src/cpp/type-conversion.cpp +++ b/src/cpp/type-conversion.cpp @@ -420,15 +420,17 @@ namespace TypeConversion { result.Set("dts", Napi::Number::New(env, static_cast(GST_BUFFER_DTS(buf)))); } if (GST_BUFFER_DURATION_IS_VALID(buf)) { - result.Set("duration", - Napi::Number::New(env, static_cast(GST_BUFFER_DURATION(buf)))); + result.Set( + "duration", Napi::Number::New(env, static_cast(GST_BUFFER_DURATION(buf))) + ); } if (GST_BUFFER_OFFSET_IS_VALID(buf)) { result.Set("offset", Napi::Number::New(env, static_cast(GST_BUFFER_OFFSET(buf)))); } if (GST_BUFFER_OFFSET_END_IS_VALID(buf)) { - result.Set("offsetEnd", - Napi::Number::New(env, static_cast(GST_BUFFER_OFFSET_END(buf)))); + result.Set( + "offsetEnd", Napi::Number::New(env, static_cast(GST_BUFFER_OFFSET_END(buf))) + ); } }