Package com.amazonaws.kinesisvideo.internal.client.mediasource

Interface MediaSourceSink

  • All Known Implementing Classes:
    ProducerStreamSink
    public interface MediaSourceSink
    Interface that acts as a consumer/sink for media frames produced by a MediaSource.

    The MediaSourceSink serves as the bridge between a MediaSource and the Kinesis Video Streams Producer SDK. It receives media frames and metadata from the MediaSource and forwards them to the underlying Kinesis Video Producer for streaming.

    Key responsibilities:

    Data flow:

     MediaSource → MediaSourceSink → KinesisVideoProducerStream → Kinesis Video Streams

    Frame delivery:

    • MediaSource calls sink.onFrame(frame) for each video/audio frame
    • Sink validates and forwards frame to the producer stream
    • Producer handles packaging, and network transmission
    See Also:
    MediaSource, KinesisVideoFrame, KinesisVideoProducerStream

    • Method Detail

      • onFrame

        void onFrame​(@Nonnull
             KinesisVideoFrame kinesisVideoFrame)
      throws KinesisVideoException
        Receives a video or audio frame from the MediaSource for streaming to Kinesis Video Streams.

        This is the primary method for frame delivery. The MediaSource calls this method for each frame it produces (video frames, audio frames, or both).

        Frame requirements:

        • Frame must contain valid encoded data (H.264, H.265, AAC, etc.)
        • Frame timestamps must be monotonically increasing
        • Key frames should be marked appropriately for video
        • Frame duration should be set for proper playback timing

        Error handling:

        • Throws KinesisVideoException if frame cannot be processed
        • MediaSource should handle exceptions and decide whether to continue or stop, combined with listening for any StreamCallbacks.
        Parameters:
        kinesisVideoFrame - the frame to be streamed, containing encoded media data and metadata
        Throws:
        KinesisVideoException - if the frame cannot be processed or streamed

      • onCodecPrivateData

        void onCodecPrivateData​(@Nullable
                        byte[] codecPrivateData)
                 throws KinesisVideoException
        Receives codec private data (codec configuration) for the default track.

        Codec private data contains essential configuration information that decoders need to properly decode the stream. Examples include:

        • H.264: SPS (Sequence Parameter Set) and PPS (Picture Parameter Set)
        • H.265: VPS, SPS, and PPS

        When to send:

        • At stream start, before sending any frames
        • When codec parameters change (e.g. resolution)
        • After stream errors that require reinitialization

        This method is equivalent to calling onCodecPrivateData(byte[], int) with the default track ID.

        Parameters:
        codecPrivateData - the codec configuration data, or null if not available
        Throws:
        KinesisVideoException - if the codec data cannot be processed

      • onCodecPrivateData

        void onCodecPrivateData​(@Nullable
                        byte[] codecPrivateData,
                        int trackId)
                 throws KinesisVideoException
        Receives codec private data (codec configuration) for a specific track in multi-track streams.

        This method is used for streams with multiple tracks (e.g., separate video and audio tracks). Each track can have its own codec configuration data.

        Example multi-track scenario:

        • Video track (ID 1) with H.264 SPS/PPS
        • Audio track (ID 2) with AAC configuration

        Track ID management:

        • Track IDs should be consistent with those used in KinesisVideoFrame
        • Track IDs must be unique within the stream
        Parameters:
        codecPrivateData - the codec configuration data for the specified track
        trackId - the unique identifier for the track this codec data applies to
        Throws:
        KinesisVideoException - if the codec data cannot be processed

      • onFragmentMetadata

        void onFragmentMetadata​(@Nonnull
                        String metadataName,
                        @Nonnull
                        String metadataValue,
                        boolean persistent)
                 throws KinesisVideoException
        Receives fragment-level metadata to be associated with the stream.

        Fragment metadata allows attaching custom key-value pairs to stream fragments. This metadata can be retrieved when consuming the stream and is useful for:

        • Adding timestamps or sensor readings
        • Marking important events or scenes
        • Storing application-specific annotations (e.g. bounding boxes)
        • Adding searchable tags for content discovery

        Usage examples:

         // Mark motion detection event
 sink.onFragmentMetadata("motion_detected", "true", false);

 // Add sensor data
 sink.onFragmentMetadata("temperature", "23.5", false);
        Parameters:
        metadataName - the name/key of the metadata field
        metadataValue - the value of the metadata field
        persistent - true if metadata should be stored permanently, false for transient metadata
        Throws:
        KinesisVideoException - if the metadata cannot be processed
        See Also:
        Fragment metadata limits

      • getProducerStream

        KinesisVideoProducerStream getProducerStream()
        Returns the underlying Kinesis Video Producer stream that receives the media data.

        Caution: Direct manipulation of the producer stream should be done carefully to avoid interfering with the normal MediaSource → MediaSourceSink flow.

        Returns:
        the underlying KinesisVideoProducerStream instance