From 4047038113aa1a3691378cb2f714ab28f81a2c5a Mon Sep 17 00:00:00 2001
From: Vanilagy <1696106+Vanilagy@users.noreply.github.com>
Date: Wed, 13 May 2026 17:27:36 +0200
Subject: [PATCH] Add doc block clarification (fixes #368)

---
 src/media-sink.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/media-sink.ts b/src/media-sink.ts
index a5192a2..c362fea 100644
--- a/src/media-sink.ts
+++ b/src/media-sink.ts
@@ -1821,6 +1821,9 @@ export class VideoSampleSink extends BaseMediaSampleSink<VideoSample> {
 	 * once, and is therefore more efficient than manually getting the sample for every timestamp. The iterator may
 	 * yield null if no frame is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link VideoSampleSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */
@@ -2120,6 +2123,9 @@ export class CanvasSink {
 	 * therefore more efficient than manually getting the canvas for every timestamp. The iterator may yield null if
 	 * no frame is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link CanvasSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */
@@ -2523,6 +2529,9 @@ export class AudioSampleSink extends BaseMediaSampleSink<AudioSample> {
 	 * once, and is therefore more efficient than manually getting the sample for every timestamp. The iterator may
 	 * yield null if no sample is available for a given timestamp.
 	 *
+	 * This method is good for sparse access of media data. If you want primarily sequential media access, prefer
+	 * {@link AudioSampleSink.samples} instead.
+	 *
 	 * @param timestamps - An iterable or async iterable of timestamps in seconds.
 	 * @param options - Options used for the underlying packet retrieval.
 	 */