Skip to content

Commit 4772bdd

Browse files
sayantacCsayantacC
authored
First cut for release_1.0.0 (#1)
1 parent 09d580e commit 4772bdd

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+6096
-1
lines changed

‎README.md‎

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,65 @@
1-
Amazon Kinesis Video Streams Parser Library
1+
# Amazon Kinesis Video Streams Parser Library
22

33
## License
44

55
This library is licensed under the Apache 2.0 License.
6+
7+
## Introduction
8+
The Amazon Kinesis Video Streams Parser Library for Java enables Java developers to parse the streams returned by `GetMedia` calls to Amazon Kinesis Video.
9+
It contains:
10+
* A streaming Mkv Parser called `StreamingMkvReader` that provides an iterative interface to read the `MkvElement`s in a stream.
11+
* Applications such as `OutputSegmentMerger` and `FragmentMetadataVisitor` built using the `StreamingMkvReader` .
12+
* A callback based parser called `EBMLParser` that minimizes data buffering and copying. `StreamingMkvReader` is built on top of `EBMLParser`
13+
* Unit tests for the applications and parsers that demonstrate how the applications work.
14+
15+
## Building from Source
16+
After you've downloaded the code from GitHub, you can build it using Maven. Use this command: `mvn clean install`
17+
18+
19+
## Details
20+
### StreamingMkvReader
21+
`StreamingMkvReader` which provides an iterative interface to read `MkvElement`s from a stream.
22+
A caller calls `nextIfAvailable` to get the next `MkvElement`. An `MkvElement` wrapped in an `Optional` is returned if a complete element is available.
23+
It buffers an individual `MkvElement` until it can return a complete `MkvElement`.
24+
The `mightHaveNext` method returns true if there is a chance that additional `MkvElements` can be returned.
25+
It returns false when the end of the input stream has been reached.
26+
27+
### MkvElement
28+
There are three types of `MkvElement` vended by a `MkvStreamReader`:
29+
* `MkvDataElement`: This encapsulates Mkv Elements that are not master elements and contain data.
30+
* `MkvStartMasterElement` : This represents the start of a *master* Mkv element that contains child elements. Child elements can be other master elements or data elements.
31+
* `MkvEndMasterElement` : This represents the end of *master* element that contains child elements.
32+
33+
### MkvElementVisitor
34+
The `MkvElementVisitor` is a visitor pattern that helps process the events in the `MkvElement` hierarchy. It has a visit
35+
method for each type of `MkvElement`.
36+
37+
## Visitors
38+
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.
39+
`OutputSegmentMerger` can be used to merge consecutive fragments that share the same *EBML* and *Track* data into a single Mkv stream with
40+
a shared *EBML* and *Segment*. This is useful for passing the output of `GetMedia` to any downstream processor that expects a single Mkv stream
41+
with one *Segment*. Its use can be seen in `OutputSegmentMergerTest`
42+
43+
`FragmentMetadataVisitor` is a `MkvElementVisitor` that collects the Kinesis Video specific meta-data (such as *FragmentNumber* and *Server Side Timestamp* )
44+
for the current fragment being processed. The `getCurrentFragmentMetadata` method can be used to get the current fragment's metadata. Similarly
45+
`getPreviousFragmentMetadata` can be used get the previous fragment's metadata. The `getMkvTrackMetadata` method can be used to get
46+
the details of a particular track.
47+
48+
`ElementSizeAndOffsetVisitor` is a visitor that writes out the metadata of the Mkv elements in a stream. For each element
49+
the name, offset, header size and data size is written out. The output uses indentation to indicate the hierarchy of master elements
50+
and their child elements. `ElementSizeAndOffsetVisitor` is useful for looking into Mkv streams, where mkvinfo fails.
51+
52+
`CountVisitor` is a visitor that can be used to count the number of Mkv elements of different types in a Mkv stream.
53+
54+
`CompositeMkvElementVisitor` is a visitor that is made up of a number of constituent visitors. It calls accept on the
55+
visited `MkvElement` for each constituent visitor in the order in which the visitors are specified.
56+
57+
## Release Notes
58+
### Release 1.0.0 (November 2017)
59+
* First release of the Amazon Kinesis Video Parser Library.
60+
* Supports Mkv elements up to version 4.
61+
* Known issues:
62+
* EBMLMaxIDLength and EBMLMaxSizeLength are hardcoded as 4 and 8 bytes respectively
63+
* Unknown EBML elements not specified in `MkvTypeInfos` are not readable by the user using `StreamingMkvReader`.
64+
* Unknown EBML elements not specified in `MkvTypeInfos` of unknown length lead to an exception.
65+
* Does not do any CRC validation for any Mkv elements with the `CRC-32` element.

‎pom.xml‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xmlns="http://maven.apache.org/POM/4.0.0"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
<properties>
7+
<maven.compiler.source>1.8</maven.compiler.source>
8+
<maven.compiler.target>1.8</maven.compiler.target>
9+
</properties>
10+
<groupId>com.amazonaws</groupId>
11+
<artifactId>amazon-kinesis-video-streams-parser-library</artifactId>
12+
<packaging>jar</packaging>
13+
<name>Amazon Kinesis Video Streams Parser Library</name>
14+
<version>1.0.0</version>
15+
<description>The Amazon Kinesis Video Streams Parser Library for Java enables Java developers to parse the streams
16+
returned by GetMedia calls to Amazon Kinesis Video.
17+
</description>
18+
19+
<scm>
20+
<url>https://github.com/aws/amazon-kinesis-video-streams-parser-library.git</url>
21+
</scm>
22+
23+
<licenses>
24+
<license>
25+
<name>Apache License Version 2.0</name>
26+
<url>http://aws.amazon.com/apache2.0/</url>
27+
<distribution>repo</distribution>
28+
</license>
29+
</licenses>
30+
31+
32+
<dependencies>
33+
<dependency>
34+
<groupId>org.projectlombok</groupId>
35+
<artifactId>lombok</artifactId>
36+
<version>1.16.18</version>
37+
<scope>provided</scope>
38+
</dependency>
39+
<dependency>
40+
<groupId>org.apache.commons</groupId>
41+
<artifactId>commons-lang3</artifactId>
42+
<version>3.6</version>
43+
</dependency>
44+
<dependency>
45+
<groupId>org.slf4j</groupId>
46+
<artifactId>slf4j-api</artifactId>
47+
<version>1.7.10</version>
48+
</dependency>
49+
50+
<!--- Test -->
51+
<dependency>
52+
<groupId>junit</groupId>
53+
<artifactId>junit</artifactId>
54+
<version>4.12</version>
55+
<scope>test</scope>
56+
</dependency>
57+
<dependency>
58+
<groupId>org.apache.logging.log4j</groupId>
59+
<artifactId>log4j-slf4j-impl</artifactId>
60+
<version>2.8.2</version>
61+
<scope>test</scope>
62+
</dependency>
63+
<dependency>
64+
<groupId>org.apache.logging.log4j</groupId>
65+
<artifactId>log4j-api</artifactId>
66+
<version>2.8.1</version>
67+
<scope>test</scope>
68+
</dependency>
69+
<dependency>
70+
<groupId>org.apache.logging.log4j</groupId>
71+
<artifactId>log4j-core</artifactId>
72+
<version>2.8.1</version>
73+
<scope>test</scope>
74+
</dependency>
75+
</dependencies>
76+
77+
<developers>
78+
<developer>
79+
<id>amazonwebservices</id>
80+
<organization>Amazon Web Services</organization>
81+
<organizationUrl>https://aws.amazon.com</organizationUrl>
82+
<roles>
83+
<role>developer</role>
84+
</roles>
85+
</developer>
86+
</developers>
87+
<build>
88+
<sourceDirectory>${project.build.directory}/generated-sources/delombok</sourceDirectory>
89+
<pluginManagement>
90+
<plugins>
91+
<plugin>
92+
<groupId>org.apache.maven.plugins</groupId>
93+
<artifactId>maven-compiler-plugin</artifactId>
94+
<version>3.2</version>
95+
<configuration>
96+
<source>1.8</source>
97+
<target>1.8</target>
98+
<encoding>UTF-8</encoding>
99+
</configuration>
100+
</plugin>
101+
</plugins>
102+
</pluginManagement>
103+
104+
<plugins>
105+
<plugin>
106+
<groupId>org.projectlombok</groupId>
107+
<artifactId>lombok-maven-plugin</artifactId>
108+
<version>1.16.18.1</version>
109+
<executions>
110+
<execution>
111+
<id>delombok</id>
112+
<phase>generate-sources</phase>
113+
<goals>
114+
<goal>delombok</goal>
115+
</goals>
116+
<configuration>
117+
<sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
118+
<encoding>UTF-8</encoding>
119+
<formatPreferences>
120+
<javaLangAsFQN>skip</javaLangAsFQN>
121+
</formatPreferences>
122+
<verbose>true</verbose>
123+
</configuration>
124+
</execution>
125+
<execution>
126+
<id>test-delombok</id>
127+
<phase>generate-test-sources</phase>
128+
<goals>
129+
<goal>testDelombok</goal>
130+
</goals>
131+
<configuration>
132+
<encoding>UTF-8</encoding>
133+
<verbose>true</verbose>
134+
</configuration>
135+
</execution>
136+
</executions>
137+
</plugin>
138+
<plugin>
139+
<groupId>org.apache.maven.plugins</groupId>
140+
<artifactId>maven-javadoc-plugin</artifactId>
141+
<version>2.10.3</version>
142+
<executions>
143+
<execution>
144+
<id>attach-javadocs</id>
145+
<goals>
146+
<goal>jar</goal>
147+
</goals>
148+
</execution>
149+
</executions>
150+
</plugin>
151+
<plugin>
152+
<groupId>org.apache.maven.plugins</groupId>
153+
<artifactId>maven-source-plugin</artifactId>
154+
<version>3.0.1</version>
155+
<executions>
156+
<execution>
157+
<id>attach-sources</id>
158+
<goals>
159+
<goal>jar</goal>
160+
</goals>
161+
</execution>
162+
</executions>
163+
</plugin>
164+
</plugins>
165+
166+
</build>
167+
</project>

‎src/main/java/com/amazonaws/kinesisvideo/parser/ebml/EBMLElementMetaData.java‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/*
2+
Copyright 2017-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License").
5+
You may not use this file except in compliance with the License.
6+
A copy of the License is located at
7+
8+
http://aws.amazon.com/apache2.0/
9+
10+
or in the "license" file accompanying this file.
11+
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and limitations under the License.
13+
*/
14+
package com.amazonaws.kinesisvideo.parser.ebml;
15+
16+
import lombok.Builder;
17+
import lombok.EqualsAndHashCode;
18+
import lombok.Getter;
19+
import lombok.ToString;
20+
21+
22+
/**
23+
* Class that represents the metadata of a single EBML element in an EBML stream.
24+
* It does not contain the actual data or content of the EBML element.
25+
*/
26+
@Getter
27+
@Builder
28+
@ToString
29+
@EqualsAndHashCode
30+
public class EBMLElementMetaData {
31+
private final EBMLTypeInfo typeInfo;
32+
private final long elementNumber;
33+
34+
public boolean isMaster() {
35+
return typeInfo.getType() == EBMLTypeInfo.TYPE.MASTER;
36+
}
37+
}

0 commit comments

Comments
 (0)