Add javadoc for Ogg opus stream classes.

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

Hide file tree

Showing 15 changed files with 188 additions and 47 deletions.
diff --git a/src/main/java/org/chenliang/oggus/ogg/OggPage.java b/src/main/java/org/chenliang/oggus/ogg/OggPage.java
@@ -2,7 +2,6 @@
 
 import com.google.common.io.LittleEndianDataOutputStream;
 import com.google.common.primitives.Bytes;
-import org.chenliang.oggus.opus.InvalidOpusException;
 
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;

diff --git a/src/main/java/org/chenliang/oggus/ogg/OggStream.java b/src/main/java/org/chenliang/oggus/ogg/OggStream.java
@@ -24,6 +24,7 @@ private OggStream(InputStream inputStream) {
      *
      * @param filePath path of an Ogg file
      * @throws FileNotFoundException if the Ogg file doesn't exist.
+     * @return OggStream
      */
     public static OggStream from(String filePath) throws FileNotFoundException {
         return new OggStream(new BufferedInputStream(new FileInputStream(filePath)));
@@ -33,6 +34,7 @@ public static OggStream from(String filePath) throws FileNotFoundException {
      * Create {@code OggStream} from an {@code InputStream}.
      *
      * @param inputStream the underlying input stream.
+     * @return OggStream
      */
     public static OggStream from(InputStream inputStream) {
         return new OggStream(inputStream);

diff --git a/src/main/java/org/chenliang/oggus/opus/CommentHeader.java b/src/main/java/org/chenliang/oggus/opus/CommentHeader.java
@@ -13,6 +13,34 @@
 import java.util.Collection;
 import java.util.Map;
 
+/**
+ * The Comment Header packet of a Ogg Opus stream. It has following structure:
+ * <pre>
+ *  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
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |      'O'      |      'p'      |      'u'      |      's'      |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |      'T'      |      'a'      |      'g'      |      's'      |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                     Vendor String Length                      |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                                                               |
+ * :                        Vendor String...                       :
+ * |                                                               |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                   User Comment List Length                    |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                 User Comment #0 String Length                 |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                                                               |
+ * :                   User Comment #0 String...                   :
+ * |                                                               |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                 User Comment #1 String Length                 |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * :                                                               :
+ * </pre>
+ */
 public class CommentHeader {
     public static final byte[] MAGIC_SIGNATURE = {'O', 'p', 'u', 's', 'T', 'a', 'g', 's'};
     private String vendor;
@@ -22,7 +50,7 @@ private CommentHeader() {
     }
 
     /**
-     * Create {@code CommentHeader} from binary data, the data must start with 'OpusTags'.
+     * Parse {@code CommentHeader} from binary data, the data must start with 'OpusTags'.
      * <p>
      * Based on the specification, tag fields are case-insensitive. They are all converted to upper case when parsing
      * from the binary data.
@@ -58,6 +86,8 @@ public static CommentHeader from(byte[] data) {
 
     /**
      * Create an empty Comment Header.
+     *
+     * @return CommentHeader
      */
     public static CommentHeader emptyHeader() {
         return new CommentHeader();
@@ -84,13 +114,18 @@ public String getVendor() {
 
     /**
      * Set Vendor
+     *
+     * @param vendor the Vendor string
      */
     public void setVendor(String vendor) {
         this.vendor = vendor;
     }
 
     /**
      * Add a tag, the key will be transformed to upper case.
+     *
+     * @param key   tag name
+     * @param value tag value
      */
     public void addTag(String key, String value) {
         this.tags.put(key.toUpperCase(), value);

diff --git a/src/main/java/org/chenliang/oggus/opus/IdHeader.java b/src/main/java/org/chenliang/oggus/opus/IdHeader.java
@@ -10,6 +10,28 @@
 
 import static java.lang.String.format;
 
+/**
+ * The Identification Header packet of a Ogg Opus stream. It has following structure:
+ *
+ * <pre>
+ *  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
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |      'O'      |      'p'      |      'u'      |      's'      |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |      'H'      |      'e'      |      'a'      |      'd'      |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |  Version = 1  | Channel Count |           Pre-skip            |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |                     Input Sample Rate (Hz)                    |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |   Output Gain (Q7.8 in dB)    | Mapping Family|               |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               :
+ * |                                                               |
+ * :               Optional Channel Mapping Table...               :
+ * |                                                               |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * </pre>
+ */
 public class IdHeader {
     public static final byte[] MAGIC_SIGNATURE = {'O', 'p', 'u', 's', 'H', 'e', 'a', 'd'};
     private int majorVersion;
@@ -26,6 +48,12 @@ public class IdHeader {
     private IdHeader() {
     }
 
+    /**
+     * Parse {@code IdHeader} from binary data, the data must start with 'OpusHead'.
+     *
+     * @param data the binary data of ID Header
+     * @return IdHeader
+     */
     public static IdHeader from(byte[] data) {
         IdHeader idHeader = new IdHeader();
         LittleEndianDataInputStream in = new LittleEndianDataInputStream(new ByteArrayInputStream(data));
@@ -70,10 +98,20 @@ public static IdHeader from(byte[] data) {
         }
     }
 
+    /**
+     * Create an empty Id Header.
+     *
+     * @return IdHeader
+     */
     public static IdHeader emptyHeader() {
         return new IdHeader();
     }
 
+    /**
+     * Dump this IdHeader to binary.
+     *
+     * @return the binary bytes representation of this IdHeader
+     */
     public byte[] dump() {
         ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
         LittleEndianDataOutputStream out = new LittleEndianDataOutputStream(byteArrayOutputStream);

diff --git a/src/main/java/org/chenliang/oggus/opus/OggOpusStream.java b/src/main/java/org/chenliang/oggus/opus/OggOpusStream.java
@@ -10,6 +10,25 @@
 import java.util.List;
 import java.util.Queue;
 
+/**
+ * A class that provide methods to read an Ogg opus stream. An Ogg Opus stream is organized as follows:
+ *
+ * <pre>
+ *    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'
+ * </pre>
+ */
 public class OggOpusStream {
     private final CommentHeader commentHeader;
     private final IdHeader idHeader;
@@ -25,58 +44,54 @@ private OggOpusStream(OggStream oggStream) throws IOException {
         this.oggStream = oggStream;
     }
 
+    /**
+     * Read Ogg Opus stream from an InputStream.
+     *
+     * @param inputStream An InputStream that could read the Ogg Opus stream.
+     * @return The OggOpusStream object
+     * @throws IOException If IO read error
+     */
     public static OggOpusStream from(InputStream inputStream) throws IOException {
         return new OggOpusStream(OggStream.from(inputStream));
     }
 
+    /**
+     * Read Ogg Opus stream from file
+     *
+     * @param filePath The file path
+     * @return The OggOpusStream object
+     * @throws IOException If IO read error
+     */
     public static OggOpusStream from(String filePath) throws IOException {
         return new OggOpusStream(OggStream.from(filePath));
     }
 
-    private IdHeader readIdHeader(OggStream oggStream) throws IOException {
-        OggPage oggPage = readOpusBosPage(oggStream);
-        streamId = oggPage.getSerialNum();
-        return IdHeader.from(oggPage.getDataPackets().get(0));
-    }
-
-    private OggPage readOpusBosPage(OggStream oggStream) throws IOException {
-        while (true) {
-            OggPage oggPage = oggStream.readPage();
-            if (oggPage == null) {
-                throw new InvalidOpusException("No ID Header data in this opus file");
-            }
-
-            if (oggPage.isBOS()) {
-                if (oggPage.getDataPackets().size() > 1) {
-                    throw new InvalidOpusException("The ID Header Ogg page must NOT contain other data");
-                }
-                return oggPage;
-            }
-        }
-    }
-
-    private CommentHeader readCommentHeader(OggStream oggStream) throws IOException {
-        byte[] commentHeaderData = new byte[0];
-        while (true) {
-            OggPage currentPage = oggStream.readPage(streamId);
-            List<byte[]> currentPagePackets = currentPage.getDataPackets();
-            if (currentPagePackets.size() != 1) {
-                throw new InvalidOpusException("Comment Header Ogg pages must only contain 1 data packet");
-            }
-            commentHeaderData = Bytes.concat(commentHeaderData, currentPagePackets.get(0));
-            if (currentPage.getGranulePosition() == 0) break;
-        }
-        return CommentHeader.from(commentHeaderData);
-    }
-
+    /**
+     * Get the Id header of this Ogg Opus stream
+     *
+     * @return IdHeader
+     */
     public IdHeader getIdHeader() {
         return this.idHeader;
     }
 
+    /**
+     * Get the Comment header of this Ogg Opus stream
+     *
+     * @return CommentHeader
+     */
     public CommentHeader getCommentHeader() {
         return this.commentHeader;
     }
 
+    /**
+     * Read an AudioDataPacket from the Ogg Opus stream. Return {@code null} if this is not more data to read.
+     *
+     * <p>If there multiple logical streams, the first Opus stream is read.</p>
+     *
+     * @return AudioDataPacket
+     * @throws IOException if IO read error
+     */
     public AudioDataPacket readAudioPacket() throws IOException {
         if (lastPageLeftAudioDataPackets.isEmpty()) {
             if (isEnd) {
@@ -121,4 +136,40 @@ public AudioDataPacket readAudioPacket() throws IOException {
         }
         return AudioDataPacket.from(data, idHeader.getStreamCount());
     }
+
+    private IdHeader readIdHeader(OggStream oggStream) throws IOException {
+        OggPage oggPage = readOpusBosPage(oggStream);
+        streamId = oggPage.getSerialNum();
+        return IdHeader.from(oggPage.getDataPackets().get(0));
+    }
+
+    private OggPage readOpusBosPage(OggStream oggStream) throws IOException {
+        while (true) {
+            OggPage oggPage = oggStream.readPage();
+            if (oggPage == null) {
+                throw new InvalidOpusException("No ID Header data in this opus file");
+            }
+
+            if (oggPage.isBOS()) {
+                if (oggPage.getDataPackets().size() > 1) {
+                    throw new InvalidOpusException("The ID Header Ogg page must NOT contain other data");
+                }
+                return oggPage;
+            }
+        }
+    }
+
+    private CommentHeader readCommentHeader(OggStream oggStream) throws IOException {
+        byte[] commentHeaderData = new byte[0];
+        while (true) {
+            OggPage currentPage = oggStream.readPage(streamId);
+            List<byte[]> currentPagePackets = currentPage.getDataPackets();
+            if (currentPagePackets.size() != 1) {
+                throw new InvalidOpusException("Comment Header Ogg pages must only contain 1 data packet");
+            }
+            commentHeaderData = Bytes.concat(commentHeaderData, currentPagePackets.get(0));
+            if (currentPage.getGranulePosition() == 0) break;
+        }
+        return CommentHeader.from(commentHeaderData);
+    }
 }
diff --git a/src/main/java/org/chenliang/oggus/opus/OpusPacket.java b/src/main/java/org/chenliang/oggus/opus/OpusPacket.java
@@ -123,11 +123,15 @@ public int getPadDataLen() {
 
     /**
      * Dump Opus packet to standard binary.
+     *
+     * @return binary byte array
      */
     public abstract byte[] dumpToStandardFormat();
 
     /**
      * Dump Opus packet to self delimiting binary.
+     *
+     * @return binary byte array
      */
     public abstract byte[] dumpToSelfDelimitingFormat();
 

diff --git a/src/test/java/org/chenliang/oggus/ogg/OggPageTest.java b/src/test/java/org/chenliang/oggus/ogg/OggPageTest.java
@@ -2,7 +2,6 @@
 
 import com.google.common.primitives.Bytes;
 import org.chenliang.oggus.TestUtil;
-import org.chenliang.oggus.opus.InvalidOpusException;
 import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;

diff --git a/src/test/java/org/chenliang/oggus/opus/AudioDataPacketTest.java b/src/test/java/org/chenliang/oggus/opus/AudioDataPacketTest.java
@@ -4,7 +4,7 @@
 import org.chenliang.oggus.TestUtil;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 
 class AudioDataPacketTest {
     @Test

diff --git a/src/test/java/org/chenliang/oggus/opus/CodeThreePacketTest.java b/src/test/java/org/chenliang/oggus/opus/CodeThreePacketTest.java
@@ -6,7 +6,9 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvSource;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class CodeThreePacketTest {
     @Test

diff --git a/src/test/java/org/chenliang/oggus/opus/CodeTwoPacketTest.java b/src/test/java/org/chenliang/oggus/opus/CodeTwoPacketTest.java
@@ -4,7 +4,10 @@
 import org.chenliang.oggus.TestUtil;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class CodeTwoPacketTest {
     @Test

diff --git a/src/test/java/org/chenliang/oggus/opus/CodeZeroPacketTest.java b/src/test/java/org/chenliang/oggus/opus/CodeZeroPacketTest.java
@@ -4,7 +4,9 @@
 import org.chenliang.oggus.TestUtil;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 
 class CodeZeroPacketTest {
     @Test

diff --git a/src/test/java/org/chenliang/oggus/opus/CommentHeaderTest.java b/src/test/java/org/chenliang/oggus/opus/CommentHeaderTest.java
@@ -3,7 +3,10 @@
 import com.google.common.primitives.Bytes;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 class CommentHeaderTest {
     @Test