Change readme and set version to 1.0.0.

leonfancy · Jul 11, 2020 · a03ecf4 · a03ecf4
1 parent 65ca13a
commit a03ecf4
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -2,93 +2,33 @@
 
 Oggus is a Java library for reading and writing Ogg Opus stream. Opus packet structure is supported.
 
-## Introduction 
+## How to use Oggus
 
-### Ogg
+Oggus library makes it easy to read and create Ogg and Opus stream.
 
-Ogg is a media container format maintained by the [Xiph.Org Foundation](https://en.wikipedia.org/wiki/Xiph.Org_Foundation). An Ogg bitstream consists of a sequence of Ogg pages. Each page begins with the characters, "OggS", to identify the stream as Ogg format.
+### Adding Oggus to your build
 
-The following is the field layout of an Ogg page header
+Oggus library is published to Maven Central. 
 
-```text
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1| Byte
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| capture_pattern: Magic number for page start "OggS"           | 0-3
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| version       | header_type   | granule_position              | 4-7
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                                                               | 8-11
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                               | bitstream_serial_number       | 12-15
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                               | page_sequence_number          | 16-19
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                               | CRC_checksum                  | 20-23
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|                               |page_segments  | segment_table | 24-27
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| ...                                                           | 28-
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-```
-
-For more description about Ogg, please refer to following links:
-- [RFC3533: The Ogg Encapsulation Format](https://tools.ietf.org/html/rfc3533)
-- [Ogg bitstream overview](https://xiph.org/ogg/doc/oggstream.html)
-
-### Opus
-
-Opus is a lossy audio coding format developed by the [Xiph.Org Foundation](https://en.wikipedia.org/wiki/Xiph.Org_Foundation). Each Opus packet begins with a TOC byte:
+To add a dependency using Maven, use the following:
 
-```text
- 0 1 2 3 4 5 6 7
-+-+-+-+-+-+-+-+-+
-| config  |s| c |
-+-+-+-+-+-+-+-+-+
 ```
-The top five bits of the TOC byte, labeled "config", encode one of 32 possible configurations of operating mode, audio bandwidth, and frame size.
-
-One additional bit, labeled "s", signals mono vs. stereo, with 0 indicating mono and 1 indicating stereo. 
-
-The remaining two bits of the TOC byte, labeled "c", code the number of frames per packet (codes 0 to 3) as follows:
-
-- 0: 1 frame in the packet
-- 1: 2 frames in the packet, each with equal compressed size
-- 2: 2 frames in the packet, with different compressed sizes
-- 3: an arbitrary number of frames in the packet
-
-For more description about Opus, please refer to [RFC6716](https://tools.ietf.org/html/rfc6716#section-3.1).
-
-### Ogg Encapsulation for the Opus Audio Codec
-
-Ogg container format can be used to encapsulate Opus audio bitstream. An Ogg Opus stream is organized as follows:
-
-```text
-   Page 0         Pages 1 ... n        Pages (n+1) ...
-+------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
-|            | |   | |   |     |   | |           | |         | |
-|+----------+| |+-----------------+| |+-------------------+ +-----
-|| ID Header|| ||  Comment Header || ||Audio Data Packet 1| | ...
-|+----------+| |+-----------------+| |+-------------------+ +-----
-|            | |   | |   |     |   | |           | |         | |
-+------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
-^      ^                           ^
-|      |                           |
-|      |                           Mandatory Page Break
-|      ID header is contained on a single page
-'Beginning Of Stream'
+<dependency>
+  <groupId>org.chenliang.oggus</groupId>
+  <artifactId>oggus</artifactId>
+  <version>1.0.0</version>
+</dependency>
 ```
 
-There are two mandatory header packets.  The first packet in the logical Ogg bitstream MUST contain the identification (ID) header, which uniquely identifies a stream as Opus audio. The second packet in the logical Ogg bitstream MUST contain the comment header, which contains user-supplied metadata. 
-
-All subsequent pages are audio data pages, and the Ogg packets they contain are audio data packets.  Each audio data packet contains one Opus packet for each of N different streams, where N is typically one for mono or stereo, but MAY be greater than one for multichannel audio. The value N is specified in the ID header, and is fixed over the entire length of the logical Ogg bitstream. 
-
-The first (N - 1) Opus packets, if any, are packed one after another into the Ogg packet, using the self-delimiting framing. The remaining Opus packet is packed at the end of the Ogg packet using the regular, undelimited framing. 
+To add a dependency using Gradle:
 
-For more information, please refer to [RFC7845](https://tools.ietf.org/html/rfc7845).
-
-## How to use Oggus
+```
+dependencies {
+    implementation("org.chenliang.oggus:oggus:1.0.0")
+}
+```
 
-Oggus library makes it easy to read Ogg and Opus stream.
+Get latest Oggus version in the [Release page](https://github.com/leonfancy/oggus/releases). 
 
 ### Read Ogg stream
 
@@ -203,6 +143,91 @@ opusPacket.dumpToStandardFormat();
 opusPacket.dumpToSelfDelimitingFormat();
 ```
 
+## Introduction to Ogg and Opus
+
+### Ogg
+
+Ogg is a media container format maintained by the [Xiph.Org Foundation](https://en.wikipedia.org/wiki/Xiph.Org_Foundation). An Ogg bitstream consists of a sequence of Ogg pages. Each page begins with the characters, "OggS", to identify the stream as Ogg format.
+
+The following is the field layout of an Ogg page header
+
+```text
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1| Byte
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| capture_pattern: Magic number for page start "OggS"           | 0-3
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| version       | header_type   | granule_position              | 4-7
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                                                               | 8-11
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                               | bitstream_serial_number       | 12-15
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                               | page_sequence_number          | 16-19
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                               | CRC_checksum                  | 20-23
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                               |page_segments  | segment_table | 24-27
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| ...                                                           | 28-
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+For more description about Ogg, please refer to following links:
+- [RFC3533: The Ogg Encapsulation Format](https://tools.ietf.org/html/rfc3533)
+- [Ogg bitstream overview](https://xiph.org/ogg/doc/oggstream.html)
+
+### Opus
+
+Opus is a lossy audio coding format developed by the [Xiph.Org Foundation](https://en.wikipedia.org/wiki/Xiph.Org_Foundation). Each Opus packet begins with a TOC byte:
+
+```text
+ 0 1 2 3 4 5 6 7
++-+-+-+-+-+-+-+-+
+| config  |s| c |
++-+-+-+-+-+-+-+-+
+```
+The top five bits of the TOC byte, labeled "config", encode one of 32 possible configurations of operating mode, audio bandwidth, and frame size.
+
+One additional bit, labeled "s", signals mono vs. stereo, with 0 indicating mono and 1 indicating stereo. 
+
+The remaining two bits of the TOC byte, labeled "c", code the number of frames per packet (codes 0 to 3) as follows:
+
+- 0: 1 frame in the packet
+- 1: 2 frames in the packet, each with equal compressed size
+- 2: 2 frames in the packet, with different compressed sizes
+- 3: an arbitrary number of frames in the packet
+
+For more description about Opus, please refer to [RFC6716](https://tools.ietf.org/html/rfc6716#section-3.1).
+
+### Ogg Encapsulation for the Opus Audio Codec
+
+Ogg container format can be used to encapsulate Opus audio bitstream. An Ogg Opus stream is organized as follows:
+
+```text
+   Page 0         Pages 1 ... n        Pages (n+1) ...
++------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
+|            | |   | |   |     |   | |           | |         | |
+|+----------+| |+-----------------+| |+-------------------+ +-----
+|| ID Header|| ||  Comment Header || ||Audio Data Packet 1| | ...
+|+----------+| |+-----------------+| |+-------------------+ +-----
+|            | |   | |   |     |   | |           | |         | |
++------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
+^      ^                           ^
+|      |                           |
+|      |                           Mandatory Page Break
+|      ID header is contained on a single page
+'Beginning Of Stream'
+```
+
+There are two mandatory header packets.  The first packet in the logical Ogg bitstream MUST contain the identification (ID) header, which uniquely identifies a stream as Opus audio. The second packet in the logical Ogg bitstream MUST contain the comment header, which contains user-supplied metadata. 
+
+All subsequent pages are audio data pages, and the Ogg packets they contain are audio data packets.  Each audio data packet contains one Opus packet for each of N different streams, where N is typically one for mono or stereo, but MAY be greater than one for multichannel audio. The value N is specified in the ID header, and is fixed over the entire length of the logical Ogg bitstream. 
+
+The first (N - 1) Opus packets, if any, are packed one after another into the Ogg packet, using the self-delimiting framing. The remaining Opus packet is packed at the end of the Ogg packet using the regular, undelimited framing. 
+
+For more information, please refer to [RFC7845](https://tools.ietf.org/html/rfc7845).
+
+
 ## License
 WTFPL: <a href="http://www.wtfpl.net/"><img
        src="http://www.wtfpl.net/wp-content/uploads/2012/12/wtfpl-badge-4.png"

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -11,7 +11,7 @@ java {
     withSourcesJar()
 }
 
-version = "0.2.0"
+version = "1.0.0"
 group = "org.chenliang.oggus"
 
 repositories {