sianao / roc-go

Golang bindings for Roc Toolkit.

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)
• C library and bindings for other languages
• end-user apps

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{
	FrameSampleRate:  44100,
	FrameChannels:    roc.ChannelSetStereo,
	FrameEncoding:    roc.FrameEncodingPcmFloat,
	FecEncoding:      roc.FecEncodingRs8m,
	ClockSource:      roc.ClockInternal,
})
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)
}

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

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{
	FrameSampleRate:  44100,
	FrameChannels:    roc.ChannelSetStereo,
	FrameEncoding:    roc.FrameEncodingPcmFloat,
	ClockSource:      roc.ClockInternal,
})
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)
}

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

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

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

	/* process samples */
}

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

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

Development

Install development dependencies:

• golangci-lint

• stringer

  go install golang.org/x/tools/cmd/stringer@latest

Run all checks:

make

Run only specific checks:

make gen|build|lint|test|testall

Update modules:

make tidy

Format code:

make fmt

Release

To release a new version:

• Create git tag

  ./tag.py --push <remote> <version>
  

  e.g.

  ./tag.py --push origin 1.2.3
  

  Or use tag.py without --push to only create a tag locally, and then push it manually.

• Wait until "Release" CI job completes and creates GitHub release draft.

• Edit GitHub release created by CI and publish it.

Authors

See here.

License

Bindings are licensed under MIT.

For details on Roc Toolkit licensing, see here.