io7m | single-page | multi-page | Aradine User Manual
1. Introduction
Previous
Front Matter
Up
3. Command Line
Next

# 2. Design And Implementation

- 2.1. Overview
- 2.2. Audio Model
  - 2.2.1. Overview
  - 2.2.2. Continuous Signals
  - 2.2.3. Discrete Signals
  - 2.2.4. Sample
  - 2.2.5. Sample Rate
  - 2.2.6. Sample Period
  - 2.2.7. Buffer
  - 2.2.8. Frame Index
  - 2.2.9. Buffer Underrun
  - 2.2.10. Audio Callback
- 2.3. Instrument Model
  - 2.3.1. Overview
  - 2.3.2. Ports
  - 2.3.3. Events
  - 2.3.4. Parameters

## 2.1. Overview

1
This section of the documentation describes the design and implementation of the aradine package.

## 2.2. Audio Model

## 2.2.1. Overview

1
The aradine package works in terms of a standard discretized sampled audio model. Informally, the system generates a buffer of audio samples at a fixed rate determined by the underlying audio hardware.

## 2.2.2. Continuous Signals

1
A continuous signal in the time domain can be considered as a function from time to amplitude. At any given time t, we can evaluate a continuous time domain signal A(t) to obtain the amplitude of the signal A at time t.

### 2.2.2.2. Continuous Signal Example

## 2.2.3. Discrete Signals

1
A discrete signal can be considered as a discretized form of a continuous signal. In digital audio systems, in modern computing environments, both time and amplitude are treated as discrete values. Time is discretized by dividing it into a fixed sample rate (typically specified in samples per second). Amplitude values are discretized by expressing them as either machine integer values of a chosen size, or floating-point values of a chosen size. The aradine package expresses amplitude values as 64-bit IEEE754 floating point values.
2
As an example, a continuous signal A could be discretized as the discrete signal Q as follows:

### 2.2.3.3. Discrete Signal Example

## 2.2.4. Sample

1
A sample is a single amplitude value in a discrete signal.

## 2.2.5. Sample Rate

1
The sample rate of a discrete signal is the number of samples that comprise one second of the signal. The unit of measurement is hertz (hz).
2
At the time of writing, most consumer audio hardware works in terms of a 48000 hz sample rate.

## 2.2.6. Sample Period

1
The sample period of a discrete signal is the length of time represented by one sample in the signal. This is a function of the sample rate of the signal. In a signal with sample rate r, the sample period p of the signal is p = 1 / r.
2
For example, in a signal that has a 48000 hz sample rate, the sample period is 1 / 48000 ≈ 0.00002083 seconds ≈ 20.83 microseconds.

## 2.2.7. Buffer

1
The physical realities of digital audio hardware and software mean that audio signals are not typically produced one-sample-at-a-time. There are many different limitations at all parts of the hardware and software stack that ultimately mean that it is more efficient to produce a buffer of samples less frequently, than a single sample more frequently. At a configurable (but constant) rate, the audio hardware and software will request a buffer of samples from applications. The buffer size specifies the number of samples that must be produced in a single request, and is typically configurable (although most hardware will have a minimum buffer size that it can handle).
2
The buffer duration of a buffer is simply the number of samples in the buffer multiplied by the sample period of the samples.
3
Buffering increases latency in the system. If an audio system is configured such that the buffer duration equals 10 milliseconds, then each time the system requests a buffer of samples, the system is essentially saying "Produce the most recent 10 milliseconds of audio for playback right now". This means that a listener is necessarily going to hear the audio 10 milliseconds later than the events that actually produced it. There is, therefore, a tension between specifying a larger buffer size in order to reduce the hardware and software overhead of producing the audio, and specifying a smaller buffer size in order to reduce the effective latency of the system.
4
For example, in a system with sample duration P and a buffer duration B, at Time = 8, the listener is going to hear the contents of the sample buffer SB0, even though the first sample in that buffer occurred at Time = 0:

### 2.2.7.5. Buffered Audio

6
At the time of writing, on most consumer and professional hardware, typical buffer sizes are in the 64-512 range. This implies a typical latency of around 2 milliseconds, which is mostly below the threshold of human perception.

## 2.2.8. Frame Index

1
A frame index is an integer index that refers to a set of samples across a set of buffers. A frame index is a non-negative relative index, with a value of 0 referring to the first sample in a buffer.
2
As an example, assume a buffer size of 8, and three signals S0, S1, and S2. At Time = 16, a frame index of 4 refers to the sample values in the buffers at Time = 20:

### 2.2.8.3. Frame Index

4
The term frame comes from the general term sampling frame in DSP. In other systems, audio signals are often divided into multiple channels. For example, stereo audio is divided into left and right channels. In an audio signal with n channels, the individual sample values in each of the channels at a given time are collectively referred to as a sampling frame (or frame, in short). For example, in a stereo audio signal A, the sample value x in the left channel at time 0, and the sample value y in the right channel at time 0 can be viewed as the frame (x, y) at time 0. Conceptually, the audio signal A can be seen as a function A(t) = (p, q), where t is time, and (p, q) is the sampling frame at time t. The aradine package only works with audio signals that have a single channel, but re-uses the term frame to refer to samples across coincident audio buffers.

## 2.2.9. Buffer Underrun

1
Much of the practical aspect of digital signal processing is concerned with avoiding buffer underrun. This occurs when the operations required to produce a buffer of samples take longer to execute than the buffer duration. Essentially, the system has asked for a buffer of samples, but it has taken the application code longer than this duration to actually produce the buffer. Therefore, the buffer of samples is not ready in time and the audio system has nothing to play! This manifests as audible glitches in the audio output.

## 2.2.10. Audio Callback

1
In the aradine package, the underlying audio system periodically requests that a buffer of samples be produced for each audio output in the system. We refer to this request as the audio callback. More precisely, we say that the underlying audio system periodically calls the aradine audio callback, and the code in the aradine package referenced by the callback performs all of the required processing and then writes out the resulting buffer of samples.

## 2.3. Instrument Model

## 2.3.1. Overview

1
The aradine package collects DSP code into instruments, and instruments can be connected together arbitrarily to form an ensemble.
2
Within an ensemble, the ports of the instruments are connected together to form a graph. A target port may be connected to at most one source port at any given time. An source port may be connected to zero or more target ports at any given time. The types of ports must match; it is not permitted to try to connect a port of an audio type to a port of a note type, for example.

## 2.3.2. Ports

1
Instruments have zero or more ports. A port may either be a source port or a target port. A target port consumes data, while a source port produces data.
2
Ports have a type. Currently, ports may have either an audio type or a note type.
3
A target port I of an audio type will, at audio callback time, consume a buffer of audio samples that was produced by whatever source port O is connected to I. If no source port is connected to I, then I will be presented with a buffer of audio samples where every sample value is equal to 0.0.
4
A target port I of a note type will, at audio callback time, consume a buffer of note events that was produced by whatever source port O is connected to I. If no source port is connected to I, then I will be presented with an empty buffer.
5
A source port O of a audio type will, at audio callback time, produce a buffer of audio samples that is then consumed by each of the target ports connected to O.
6
A source port O of a note type will, at audio callback time, produce a buffer of note events that is then consumed by each of the target ports connected to O.

## 2.3.3. Events

1
An event is a discrete, typed, timestamped value delivered to an instrument.
2
An event may be one of the following base types:

### 2.3.3.3. Event Base Types

- A note event type.
- A configuration event type.

4
A note-typed event may be one of the following types:

### 2.3.3.5. Note Event Types

- A note-on event type. This event type is published when the user presses a key on a musical keyboard.
- A note-off event type. This event type is published when the user releases a key on a musical keyboard.
- A pitch-bend event type. This event type is published when the user touches the pitch bend control on a musical keyboard.

6
A configuration-typed event may be one of the following types:

### 2.3.3.7. Configuration Event Types

- A buffer-size-changed event type. This event type is published when the underlying audio system is reconfigured to use a different buffer size.
- A sample-rate-changed event type. This event type is published when the underlying audio system is reconfigured to use a different sample rate.
- A parameter-changed event type. This event type is published when the value of a parameter is changed on an instrument.

8
Events are typically delivered to instruments via an event buffer. An event buffer is an opaque buffer type that, given a frame index, returns all events that occurred at that frame index.

## 2.3.4. Parameters

1
Instruments have zero or more parameters. A parameter is effectively a named and typed mutable variable, the value of which can be read and/or modified (atomically) at any time. Parameters have unique (within an instrument) integer identifiers, and humanly-readable string labels. Additionally, parameters that are of numeric types are declared with minimum and maximum value range constraints. All parameters also have defined default values.
2
A parameter may be of one of the following types:

### 2.3.4.3. Parameter Types

- 64-bit integer.
- 64-bit floating point.
- Sample map.

1. Introduction
Previous
Front Matter
Up
3. Command Line
Next
io7m | single-page | multi-page | Aradine User Manual