README.md

Go bindings for Roc Toolkit

This library provides Go (golang) bindings for Roc Toolkit, a toolkit for real-time audio streaming over the network.

About Roc

Key features of Roc Toolkit:

• real-time streaming with guaranteed latency;
• robust work on unreliable networks like Wi-Fi, due to use of Forward Erasure Correction codes;
• CD-quality audio;
• multiple profiles for different CPU and latency requirements;
• relying on open, standard protocols, like RTP and FECFRAME;
• interoperability with both Roc and third-party software.

Compatible Roc Toolkit senders and receivers include:

• cross-platform command-line tools
• modules for sound servers (PulseAudio, PipeWire, macOS CoreAudio)
• C library and bindings for other languages
• applications (Android)

Documentation

Documentation for the bindings is available on pkg.go.dev.

Documentation for the underlying C API can be found here.

Quick start

Sender

import (
	"github.com/roc-streaming/roc-go/roc"
)

context, err := roc.OpenContext(roc.ContextConfig{})
if err != nil {
	panic(err)
}
defer context.Close()

sender, err := roc.OpenSender(roc.SenderConfig{
	FrameEncoding: roc.MediaEncoding{
		Rate:     44100,
		Format:   roc.FormatPcmFloat32,
		Channels: roc.ChannelLayoutStereo,
	},
	PacketEncoding: roc.PacketEncodingAvpL16Stereo,
	FecEncoding:    roc.FecEncodingRs8m,
	ClockSource:    roc.ClockSourceInternal,
})
if err != nil {
	panic(err)
}
defer sender.Close()

sourceEndpoint, err := roc.ParseEndpoint("rtp+rs8m://192.168.0.1:10001")
if err != nil {
	panic(err)
}

repairEndpoint, err := roc.ParseEndpoint("rs8m://192.168.0.1:10002")
if err != nil {
	panic(err)
}

controlEndpoint, err := roc.ParseEndpoint("rtcp://192.168.0.1:10003")
if err != nil {
	panic(err)
}

err = sender.Connect(roc.SlotDefault, roc.InterfaceAudioSource, sourceEndpoint)
if err != nil {
	panic(err)
}

err = sender.Connect(roc.SlotDefault, roc.InterfaceAudioRepair, repairEndpoint)
if err != nil {
	panic(err)
}

err = sender.Connect(roc.SlotDefault, roc.InterfaceAudioControl, controlEndpoint)
if err != nil {
	panic(err)
}

for {
	samples := make([]float32, 320)

	/* fill samples */

	err = sender.WriteFloats(samples)
	if err != nil {
		panic(err)
	}
}

Receiver

import (
	"github.com/roc-streaming/roc-go/roc"
)

context, err := roc.OpenContext(roc.ContextConfig{})
if err != nil {
	panic(err)
}
defer context.Close()

receiver, err := roc.OpenReceiver(roc.ReceiverConfig{
	FrameEncoding: roc.MediaEncoding{
		Rate:     44100,
		Format:   roc.FormatPcmFloat32,
		Channels: roc.ChannelLayoutStereo,
	},
	ClockSource: roc.ClockSourceInternal,
})
if err != nil {
	panic(err)
}
defer receiver.Close()

sourceEndpoint, err := roc.ParseEndpoint("rtp+rs8m://0.0.0.0:10001")
if err != nil {
	panic(err)
}

repairEndpoint, err := roc.ParseEndpoint("rs8m://0.0.0.0:10002")
if err != nil {
	panic(err)
}

controlEndpoint, err := roc.ParseEndpoint("rtcp://0.0.0.0:10003")
if err != nil {
	panic(err)
}

err = receiver.Bind(roc.SlotDefault, roc.InterfaceAudioSource, sourceEndpoint)
if err != nil {
	panic(err)
}

err = receiver.Bind(roc.SlotDefault, roc.InterfaceAudioRepair, repairEndpoint)
if err != nil {
	panic(err)
}

err = receiver.Bind(roc.SlotDefault, roc.InterfaceAudioControl, controlEndpoint)
if err != nil {
	panic(err)
}

for {
	samples := make([]float32, 320)

	err = receiver.ReadFloats(samples)
	if err != nil {
		panic(err)
	}

	/* process samples */
}

Installation

You will need to have Roc Toolkit library and headers installed system-wide. Refer to official build instructions on how to install it.

After installing libroc, you can install bindings using regular go get:

go get github.com/roc-streaming/roc-go/roc

Versioning

Go bindings and the C library both use semantic versioning.

Bindings are compatible with the C library when:

• major version of bindings is same as major version of C library
• minor version of bindings is same or higher as minor version of C library

Patch versions of bindings and C library are independent.

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).

Hacking

Contributions are always welcome! You can find issues needing help using help wanted and good first issue labels.

See HACKING.md for details about the project internals.

Authors

See here.

License

Bindings are licensed under MIT.

For details on Roc Toolkit licensing, see here.