audiosocket

package module

v0.2.1 Latest Latest Go to latest Published: May 18, 2023 License: Apache-2.0 Imports: 5 Imported by: 2

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/CyCoreSystems/audiosocket

Links

Open Source Insights

README ¶

AudioSocket

AudioSocket is a simple TCP-based protocol for sending and receiving realtime audio streams.

There exists a protocol definition (below), a Go library, and Asterisk application and channel interfaces.

NOTE: as of 2020-01-15, AudioSocket has been included in the upstream Asterisk system. While I am leaving the Asterisk patches here for use with previous versions, the Asterisk code in this repository should be considered obsolete. The Go code is up-to-date, maintained, and this is the primary source for it.

Protocol definition

The singular design goal of AudioSocket is to present the simplest possible audio streaming protocol, initially based on the constraints of Asterisk audio. Each packet contains a three-byte header and a variable payload. The header is composed of a one-byte type and a two-byte length indicator.

The minimum message length is three bytes: type and payload-length. Hangup indication, for instance, is 0x00 0x00 0x00.

Types

0x00 - Terminate the connection (socket closure is also sufficient)
0x01 - Payload will contain the UUID (16-byte binary representation) for the audio stream
0x10 - Payload is signed linear, 16-bit, 8kHz, mono PCM (little-endian)
0xff - An error has occurred; payload is the (optional) application-specific error code. Asterisk-generated error codes are listed below.

Payload length

The payload length is a 16-bit unsigned integer (big endian) indicating how many bytes are in the payload.

Payload

The content of the payload is defined by the header: type and length.

Asterisk error codes

Error codes are application-specific. The error codes for Asterisk are single-byte, bit-packed error codes:

0x01 - hangup of calling party
0x02 - frame forwarding error
0x04 - memory (allocation) error

Asterisk usage

There are two Asterisk implementations: a channel interface and a dialplan application interface. Each of these lends itself to simplify a different use-case, but they work in exactly the same way.

The following examples demonstrate an AudioSocket connection to a server at server.example.com running on TCP port 9092. The UUID (which is chosen arbitrarily) of the call is 40325ec2-5efd-4bd3-805f-53576e581d13.

Dialplan application:

exten = 100,1,Verbose("Call to AudioSocket via Dialplan Application")
 same = n,Answer()
 same = n,AudioSocket(40325ec2-5efd-4bd3-805f-53576e581d13,server.example.com:9092)
 same = n,Hangup()

Channel interface:

exten = 101,1,Verbose("Call to AudioSocket via Channel interface")
 same = n,Answer()
 same = n,Dial(AudioSocket/server.example.com:9092/40325ec2-5efd-4bd3-805f-53576e581d13)
 same = n,Hangup()

Documentation ¶

Index ¶

Constants
func GetID(r io.Reader) (uuid.UUID, error)
func SendSlinChunks(w io.Writer, chunkSize int, input []byte) error
type ErrorCode
type Kind
type Message

Constants ¶

View Source

const (
	// KindHangup indicates the message is a hangup signal
	KindHangup = 0x00

	// KindID indicates the message contains the unique identifier of the call
	KindID = 0x01

	// KindSilence indicates the presence of silence on the line
	KindSilence = 0x02

	// KindSlin indicates the message contains signed-linear audio data
	KindSlin = 0x10

	// KindError indicates the message contains an error code
	KindError = 0xff
)

View Source

const (
	// ErrNone indicates that no error is present
	ErrNone = 0x00

	// ErrAstHangup indicates that the call has hung up
	ErrAstHangup = 0x01

	// ErrAstFrameForwarding indicates that Asterisk had an error trying to forward an audio frame
	ErrAstFrameForwarding = 0x02

	// ErrAstMemory indicates that Asterisk had a memory/allocation erorr
	ErrAstMemory = 0x04

	// ErrUnknown indicates that the received error from Asterisk is unknown
	ErrUnknown = 0xff
)

View Source

const DefaultSlinChunkSize = 320 // 8000Hz * 20ms * 2 bytes

DefaultSlinChunkSize is the number of bytes which should be sent per slin AudioSocket message. Larger data will be chunked into this size for transmission of the AudioSocket.

Variables ¶

This section is empty.

Functions ¶

func GetID ¶ added in v0.2.0

func GetID(r io.Reader) (uuid.UUID, error)

GetID reads the unique ID from the first Message received. This should only be called once per connection, and it must be called before anything else is read from the connection.

func SendSlinChunks ¶ added in v0.2.0

func SendSlinChunks(w io.Writer, chunkSize int, input []byte) error

SendSlinChunks takes signed linear data and sends it over an AudioSocket connection in chunks of the given size.

Types ¶

type ErrorCode ¶

type ErrorCode byte

ErrorCode indicates an error, if present

type Kind ¶

type Kind byte

Kind is a message type indicator

type Message ¶

type Message []byte

Message describes an audiosocket message/packet

func HangupMessage ¶

func HangupMessage() Message

HangupMessage creates a new Message indicating a hangup

func IDMessage ¶

func IDMessage(id uuid.UUID) Message

IDMessage creates a new Message

func MessageFromData ¶

func MessageFromData(in []byte) Message

MessageFromData parses an audiosocket message into a Message

func NextMessage ¶

func NextMessage(r io.Reader) (Message, error)

NextMessage reads and parses the next message from an audiosocket connection

func SlinMessage ¶

func SlinMessage(in []byte) Message

SlinMessage creates a new Message from signed linear audio data

func (Message) ContentLength ¶

func (m Message) ContentLength() uint16

ContentLength returns the length of the payload of the message

func (Message) ErrorCode ¶

func (m Message) ErrorCode() ErrorCode

ErrorCode returns the coded error of the message, if present

func (Message) ID ¶ added in v0.2.0

func (m Message) ID() (uuid.UUID, error)

ID returns the session's unique ID if and only if the Message is the initial ID message. Normally, you would call GetID on the socket instead of manually running this function.

func (Message) Kind ¶

func (m Message) Kind() Kind

Kind returns the type of the message

func (Message) Payload ¶

func (m Message) Payload() []byte

Payload returns the data of the payload of the message

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
examples
playfile

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL