stephengold / j-ogg-all

Open-source JVM libraries for reading Ogg bitstreams and decoding the media they contain.

J-ogg-all Project

The J-ogg-all Project provides 2 JVM libraries for reading Ogg bitstreams and decoding media they contain.

It contains 2 subprojects:

1. library: builds the full "j-ogg-all" runtime library, including decoders for Vorbis, Free Lossless Audio Codec (FLAC), and Theora media. This library also provides optional interfaces to the Java Media Framework (JMF).
2. vorbis: builds a reduced library ("j-ogg-vorbis") for decoding Vorbis audio only (no support for FLAC, Theora, or JMF).

Complete source code (in Java) is provided under an informal license.

Contents of this document

• Important features
• What's missing
• How to add j-ogg-all to an existing project
• How to add j-ogg-vorbis to an existing project
• How to build the project from source
• Downloads
• Conventions
• External links
• History

Important features

• read bitstreams and metadata from Ogg containers
• decode Vorbis audio
• decode FLAC audio
• extract album art from Vorbis comments

Jump to the table of contents

What's missing

• The Theora decoder is very incomplete.
• No decoders are provided for:
  • Constrained Energy Lapped Transform (CELT) audio
  • Continuous Media Markup Language (CMML)
  • Daala video
  • Opus interactive audio
  • Speex audio

Jump to the table of contents

How to add j-ogg-all to an existing project

The j-ogg-all library is available pre-built. It depends on the Java Media Framework. Adding j-ogg-all to an existing JVM project should be a simple matter of adding these libraries to the classpath.

For projects built using Maven or Gradle, it is sufficient to add a dependency on j-ogg-all. The build tool should automatically resolve the dependency on JMF.

Gradle-built projects

Add to the project’s "build.gradle" or "build.gradle.kts" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:j-ogg-all:1.0.5")
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

Maven-built projects

Add to the project’s "pom.xml" file:

<repositories>
  <repository>
    <id>mvnrepository</id>
    <url>https://repo1.maven.org/maven2/</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>j-ogg-all</artifactId>
  <version>1.0.5</version>
</dependency>

Jump to the table of contents

How to add j-ogg-vorbis to an existing project

The j-ogg-vorbis library is available pre-built. Adding j-ogg-vorbis to an existing JVM project should be a simple matter of adding this library to the classpath.

Gradle-built projects

Add to the project’s "build.gradle" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:j-ogg-vorbis:1.0.5")
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

Maven-built projects

Add to the project’s "pom.xml" file:

<repositories>
  <repository>
    <id>mvnrepository</id>
    <url>https://repo1.maven.org/maven2/</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>j-ogg-vorbis</artifactId>
  <version>1.0.5</version>
</dependency>

Jump to the table of contents

How to build the project from source

1. Install a Java Development Kit (JDK), if you don't already have one.
2. Point the JAVA_HOME environment variable to your JDK installation: (In other words, set it to the path of a directory/folder containing a "bin" that contains a Java executable. That path might look something like "C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot" or "/usr/lib/jvm/java-17-openjdk-amd64/" or "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" .)

• using Bash or Zsh: export JAVA_HOME=" path to installation "
• using Fish: set -g JAVA_HOME " path to installation "
• using Windows Command Prompt: set JAVA_HOME=" path to installation "
• using PowerShell: $env:JAVA_HOME = ' path to installation '

3. Download and extract the j-ogg-all source code from GitHub:

• using Git:
  • git clone https://github.com/stephengold/j-ogg-all.git
  • cd j-ogg-all
  • git checkout -b latest 1.0.5
• using a web browser:
  • browse to the latest release
  • follow the "Source code (zip)" link
  • save the ZIP file
  • extract the contents of the saved ZIP file
  • cd to the extracted directory/folder

4. Run the Gradle wrapper:

• using Bash or Fish or PowerShell or Zsh: ./gradlew build
• using Windows Command Prompt: .\gradlew build

After a successful build, Maven artifacts will be found in "library/build/libs" and "vorbis/build/libs".

You can install the artifacts to your local Maven repository:

• using Bash or Fish or PowerShell or Zsh: ./gradlew install
• using Windows Command Prompt: .\gradlew install

You can restore the project to a pristine state:

• using Bash or Fish or PowerShell or Zsh: ./gradlew clean
• using Windows Command Prompt: .\gradlew clean

Jump to the table of contents

Downloads

Releases can be downloaded from GitHub or from the Maven Central Repository:

• j-ogg-all
• j-ogg-vorbis

Jump to the table of contents

Conventions

Package names begin with de.jarnbjo.

The source code is compatible with JDK 7. The pre-built libraries are compatible with JDK 8.

Jump to the table of contents

External links

• reference implementation of the Ogg container format
• reference implementation of the Vorbis codec
• Vorbis samples

Jump to the table of contents

History

The j-ogg-all project was created by Tor-Einar Jarnbjo circa 2002, probably based on reference implementations in C.

In March 2021, Stephen Gold revived the project at GitHub and added Gradle build scripts.

In September 2022, Robert Pengelly contributed code to retrieve album art from Vorbis media.

In February 2023, the "library" and "vorbis" subprojects split off.

Jump to the table of contents

j-ogg-all's Issues

Extract album art.

Not exactly an issue but how do you extract the album art? I know that it's within the comment header identified by METADATA_BLOCK_PICTURE and that it's base64 encoded, I just don't know how to extract the image after decoding it as it starts with 8 bytes before the mimetype and I don't know how to get to the actual image data.

I tried googling it but I can't find anything (at least nothing that helps) and I've looked at other projects but they don't seem to have an implementation to extract the image.

[Question] Mixing multiple ogg/vorbis files into one ogg/vorbis stream/file

Hi,

I want to implement software mixer that mixes multiple ogg/vorbis files (volume of each source should be adjustable) into the single ogg/vorbis stream/file. Is your library a proper tool for the project? If yes, what would be some high level steps for achieving this?

Thanks!

Fails to play local files.

If I use a URL to play a file then it works as expected but when I download the file and try playing it locally I get a header error.

It finds the first header but not any other headers after that as its all zeros (I think the getNextOggPacket() maybe returning null).