This library provides JNI bindings for Roc Toolkit, a toolkit for real-time audio streaming over the network.
The bindings can be used in Java, Kotlin, and other JVM-based languages.
Android support included!
Compatible senders and receivers include:
- command-line tools
- sound server modules (PulseAudio, PipeWire)
- C library
- Go bindings
Key features:
- real-time streaming with guaranteed latency;
- restoring lost packets using Forward Erasure Correction codes;
- converting between the sender and receiver clock domains;
- CD-quality audio;
- multiple profiles for different CPU and latency requirements;
- portability;
- relying on open, standard protocols.
Documentation for the Java API generated from javadoc comments can be found on javadoc.io.
Documentation for the C API can be found here.
import org.rocstreaming.roctoolkit;
final String MY_RECEIVER_IP = "192.168.0.1";
final int MY_RECEIVER_SOURCE_PORT = 10001;
final int MY_RECEIVER_REPAIR_PORT = 10002;
final int MY_SAMPLE_RATE = 44100;
try (Context context = new Context()) {
SenderConfig config = new SenderConfig.Builder(SAMPLE_RATE,
ChannelSet.STEREO,
FrameEncoding.PCM_FLOAT)
.fecEncoding(FecEncoding.RS8M)
.build();
try (Sender sender = new Sender(context, config)) {
Endpoint sourceEndpoint = new Endpoint(Protocol.RTP_RS8M_SOURCE, MY_RECEIVER_IP, MY_RECEIVER_SOURCE_PORT);
Endpoint repairEndpoint = new Endpoint(Protocol.RS8M_REPAIR, MY_RECEIVER_IP, MY_RECEIVER_REPAIR_PORT);
sender.connect(Slot.DEFAULT, Interface.AUDIO_SOURCE, sourceEndpoint);
sender.connect(Slot.DEFAULT, Interface.AUDIO_REPAIR, repairEndpoint);
while (/* not stopped */) {
float[] samples = /* generate samples */
sender.write(samples);
}
}
}
import org.rocstreaming.roctoolkit;
final String MY_RECEIVER_IP = "0.0.0.0";
final int MY_RECEIVER_SOURCE_PORT = 10001;
final int MY_RECEIVER_REPAIR_PORT = 10002;
final int MY_SAMPLE_RATE = 44100;
final int MY_SAMPLE_BATCH = 320;
try (Context context = new Context()) {
ReceiverConfig config = new ReceiverConfig.Builder(SAMPLE_RATE,
ChannelSet.STEREO,
FrameEncoding.PCM_FLOAT)
.build();
try (Receiver receiver = new Receiver(context, config)) {
Endpoint sourceEndpoint = new Endpoint(Protocol.RTP_RS8M_SOURCE, MY_RECEIVER_IP, MY_RECEIVER_SOURCE_PORT);
Endpoint repairEndpoint = new Endpoint(Protocol.RS8M_REPAIR, MY_RECEIVER_IP, MY_RECEIVER_REPAIR_PORT);
receiver.bind(Slot.DEFAULT, Interface.AUDIO_SOURCE, sourceEndpoint);
receiver.bind(Slot.DEFAULT, Interface.AUDIO_REPAIR, repairEndpoint);
while (/* not stopped */) {
float[] samples = new float[MY_SAMPLE_BATCH];
receiver.read(samples);
/* process received samples */
}
}
}
Java bindings and the C library both use semantic versioning.
Rules prior to 1.0.0 release:
- According to semantic versioning, there is no compatibility promise until 1.0.0 is released. Small breaking changes are possible. For convenience, breaking changes are introduced only in minor version updates, but not in patch version updates.
Rules starting from 1.0.0 release:
-
The first two components (major and minor) of the bindings and the C library versions correspond to each other. The third component (patch) is indepdendent.
Bindings are compatible with the C library if its major version is the same, and minor version is the same or higher.
For example, version 1.2.3 of the bindings would be compatible with 1.2.x and 1.3.x, but not with 1.1.x (minor version is lower) or 2.x.x (major version is different).
Note that prebuilt AAR package for Android already ships the right version of libroc, so you don't need to bother with compatibility bewteen bindings and libroc if you're using AAR.
Add mavenCentral repository in build.gradle
file:
repositories {
mavenCentral()
}
Add dependency to project (versions):
implementation 'org.roc-streaming.roctoolkit:roc-android:<VERSION>'
First, follow official instructions to install libroc system-wide. Take care to pick the right version as described above.
Then run:
./gradlew build
This will install dependencies inside docker and run build:
./scripts/android_docker.sh build
This will start emulator inside docker and run tests on it:
./scripts/android_docker.sh test
First, export required environment variables:
export API=28
export NDK_VERSION=21.1.6352462
export BUILD_TOOLS_VERSION=28.0.3
export CMAKE_VERSION=3.10.2.4988404
Then install Android components:
sdkmanager "platforms;android-${API}"
sdkmanager "build-tools;${BUILD_TOOLS_VERSION}"
sdkmanager "ndk;${NDK_VERSION}"
sdkmanager "cmake;${CMAKE_VERSION}"
Also install build-time dependencies of Roc Toolkit, e.g. on macOS run:
brew install scons ragel gengetopt
Now we can download and build Roc Toolkit:
./scripts/android/build_roc.sh
And finally build bindings and package everything into AAR:
cd android
./gradlew build
Optionally, run tests on device or emulator (you'll have to create one):
cd android
./gradlew cAT --info --stacktrace
Build (native code and Java code):
./gradlew build
Build only native code:
./gradlew roc_jni:build
Run tests:
./gradlew test
If libroc is not in default path you can specify ROC_INCLUDE_PATH
(path to roc headers) and ROC_LIBRARY_PATH
(path to roc library) variables with:
- environment variables
- gradle system variables
Additional compilation and linking flags can be specified respectively with CFLAGS
and LDFLAGS
gradle system variables
This command will pull docker image, install Android SDK and NDK inside it, download and build Roc Toolkit, build JNI bindings, and package everything into AAR:
./scripts/android_docker.sh build
To run instrumented tests in Android emulator inside docker image, use this:
./scripts/android_docker.sh test
To clean build results and remove docker container, run this:
./scripts/android_docker.sh clean
If desired, you can export some variables for Android environment configuration; each variable has default value and is optional:
export JAVA_VERSION=8
export API=28
export NDK_VERSION=21.1.6352462
export BUILD_TOOLS_VERSION=28.0.3
export CMAKE_VERSION=3.10.2.4988404
export AVD_IMAGE=default
export AVD_ARCH=x86_64
./scripts/android_docker.sh [build|test]
Additional information on the env-android
docker image, which is used by this script, is available here.
There is a helper script named scripts/android_device.sh
that takes care of creating and booting up AVDs.
It is used in docker and on CI, but you can also use it directly. Supported commands are:
-
create
an AVD:./scripts/android_device.sh create --api=<API> --image=<IMAGE> --arch=<ARCH> --name=<AVD-NAME>
The string
"system-images;android-<API>;<IMAGE>;<ARCH>"
defines the emulator system image to be installed (it must be present in the list offered bysdkmanager --list
) -
start
device and wait until boot is completed:./scripts/android_device.sh start --name=<AVD-NAME>
Generate docs:
./gradlew javadoc
Release workflow:
- make github release with tag version, e.g.
v0.1.0
- GitHub Actions will run release step and publish artifacts to artifactory
Followed env variables should be set in GitHub Actions:
OSSRH_USERNAME
- Sonatype OSSRH userOSSRH_PASSWORD
- Sonatype OSSRH passwordSIGNING_KEY_ID
- gpg key idSIGNING_PASSWORD
- gpg passphraseSIGNING_KEY
- gpg private key
See here.
Bindings are licensed under MIT.
For details on Roc Toolkit licensing, see here.