This library is licensed under the Apache 2.0 License.
The Amazon Kinesis Video Streams Parser Library for Java enables Java developers to parse the streams returned by GetMedia calls to Amazon Kinesis Video.
It contains:
StreamingMkvReader that provides an iterative interface to read the MkvElements in a stream.OutputSegmentMerger and FragmentMetadataVisitor built using the StreamingMkvReader .EBMLParser that minimizes data buffering and copying. StreamingMkvReader is built on top of EBMLParserAfter you've downloaded the code from GitHub, you can build it using Maven. Use this command: mvn clean install
StreamingMkvReader which provides an iterative interface to read MkvElements from a stream.
A caller calls nextIfAvailable to get the next MkvElement. An MkvElement wrapped in an Optional is returned if a complete element is available.
It buffers an individual MkvElement until it can return a complete MkvElement.
The mightHaveNext method returns true if there is a chance that additional MkvElements can be returned.
It returns false when the end of the input stream has been reached.
There are three types of MkvElement vended by a MkvStreamReader:
MkvDataElement: This encapsulates Mkv Elements that are not master elements and contain data. MkvStartMasterElement : This represents the start of a master Mkv element that contains child elements. Child elements can be other master elements or data elements.MkvEndMasterElement : This represents the end of master element that contains child elements.The MkvElementVisitor is a visitor pattern that helps process the events in the MkvElement hierarchy. It has a visit
method for each type of MkvElement.
A GetMedia call to Kinesis Video vends a stream of fragments where each fragment is encapsulated in a Mkv stream containing EBML and Segment elements.
OutputSegmentMerger can be used to merge consecutive fragments that share the same EBML and Track data into a single Mkv stream with
a shared EBML and Segment. This is useful for passing the output of GetMedia to any downstream processor that expects a single Mkv stream
with one Segment. Its use can be seen in OutputSegmentMergerTest
FragmentMetadataVisitor is a MkvElementVisitor that collects the Kinesis Video specific meta-data (such as FragmentNumber and Server Side Timestamp )
for the current fragment being processed. The getCurrentFragmentMetadata method can be used to get the current fragment's metadata. Similarly
getPreviousFragmentMetadata can be used get the previous fragment's metadata. The getMkvTrackMetadata method can be used to get
the details of a particular track.
ElementSizeAndOffsetVisitor is a visitor that writes out the metadata of the Mkv elements in a stream. For each element
the name, offset, header size and data size is written out. The output uses indentation to indicate the hierarchy of master elements
and their child elements. ElementSizeAndOffsetVisitor is useful for looking into Mkv streams, where mkvinfo fails.
CountVisitor is a visitor that can be used to count the number of Mkv elements of different types in a Mkv stream.
CompositeMkvElementVisitor is a visitor that is made up of a number of constituent visitors. It calls accept on the
visited MkvElement for each constituent visitor in the order in which the visitors are specified.
FrameVisitor is a visitor used to process the frames in the output of a GetMedia call. It invokes an implementation of the
FrameVisitor.FrameProcessor and provides it with a Frame object and the metadata of the track to which the Frame belongs.
CopyVisitor is a visitor used to copy the raw bytes of the Mkv elements in a stream to an output stream.
The GetMediaResponseStreamConsumer is an abstract class used to consume the output of a GetMedia* call to Kinesis Video in a streaming fashion.
It supports a single abstract method called process that is invoked to process the streaming payload of a GetMedia response.
The first parameter for process method is the payload inputStream in a GetMediaResult returned by a call to GetMedia.
Implementations of the process method of this interface should block until all the data in the inputStream has been
processed or the process method decides to stop for some other reason. The second argument is a FragmentMetadataCallback
which is invoked at the end of every processed fragment. The GetMediaResponseStreamConsumer provides a utility method
processWithFragmentEndCallbacks that can be used by child classes to implement the end of fragment callbacks.
The process method can be implemented using a combination of the visitors described earlier.
The MergedOutputPiper extends GetMediaResponseStreamConsumer to merge consecutive mkv streams in the output of GetMedia
and pipes the merged stream to the stdin of a child process. It is meant to be used to pipe the output of a GetMedia* call to a processing application that can not deal
with having multiple consecutive mkv streams. Gstreamer is one such application that requires a merged stream.
KinesisVideoExample is an example that shows how the StreamingMkvReader and the different visitors can be integrated
with the AWS SDK for the Kinesis Video. This example provides examples for
OutputSegmentMerger, FragmentMetadataVisitor visitors
along with a local one as part of the same CompositeMkvElementVisitor visitor.KinesisVideoRendererExample shows parsing and rendering of KVS video stream fragments using JCodec(http://jcodec.org/) that were ingested using Producer SDK GStreamer sample application.
testExample in KinesisVideoRendererExampleTest. After starting the unitTest you should be able to view the frames in a JFrame.try {
ImageIO.write(renderImage, "png", new File(String.format("frame-capture-%s.png", UUID.randomUUID())));
} catch (IOException e) {
log.warn("Couldn't convert to a PNG", e);
}PutMediaWorker but also streams sent to Kinesis Video Streams using GStreamer Demo application (https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp)KinesisVideoGStreamerPiperExample is an example for continuously piping the output of GetMedia calls from a Kinesis Video stream to GStreamer.
The test KinesisVideoGStreamerPiperExampleTest provides an example that pipes the output of a KVS GetMedia call to a Gstreamer pipeline.
The Gstreamer pipeline is a toy example that demonstrates that Gstreamer can parse the mkv passed into it.
Kinesis Video - Rekognition examples demonstrate how to combine Rekognition outputs (JSON) with KinesisVideo Streams output (H264 fragments) and render the frames with overlapping bounding boxes.
KinesisVideoRekognitionIntegrationExample decodes H264 frames and renders them with bounding boxes locally using JFrame. To run the sample, run KinesisVideoRekognitionIntegrationExampleTest with
appropriate inputs.
KinesisVideoRekognitionLambdaExample decodes H264 frames, overlaps bounding boxes, encodes to H264 frames again and ingests them into a new Kinesis Video streams using Kinesis Video Producer SDK.
To run the sample follow the below steps:
mvn package from 'amazon-kinesis-video-streams-parser-library' folder. Upload './target/amazon-kinesis-video-streams-parser-library-$VERSION-shaded.jar' file to a S3 bucket.LambdaExampleCFnTemplate.yml in the github package.OputputSegmentMerger to enable creation of a playable MKV file from a sparse KVS stream.GetMediaResponseStreamConsumer as an abstract class used to consume the output of a GetMedia* call
to Kinesis Video in a streaming fashion. Child classes will use visitors to implement different consumers.MergedOutputPiper extends GetMediaResponseStreamConsumer to merge consecutive mkv streams in the output of GetMedia
and pipes the merged stream to the stdin of a child process.MergedOutputPiper.KinesisVideoRekognitionIntegrationExample, the decode/renderer sample using JCodec may not be able to decode all mkv files.KinesisVideoRendererExample, the decode/renderer sample using JCodec may not be able to decode all mkv files.MkvTypeInfos are not readable by the user using StreamingMkvReader.MkvTypeInfos of unknown length lead to an exception.CRC-32 element.