Build a Guitar Synthesizer: Play Musical Tablature in Python

Create a New Project and Install Dependencies

There are many ways to create and manage Python projects. In this tutorial, you’ll use Poetry as a convenient tool for dependency management. If you haven’t already, then install Poetry—for example, with pipx—and start a new project using the src/ folder layout to keep your code organized:

$ poetry new --src --name digitar digital-guitar/
Created package digitar in digital-guitar

This will result in the folder structure below, which includes placeholder files with your project’s metadata and source code that you’ll fill out later:

digital-guitar/
│
├── src/
│   └── digitar/
│       └── __init__.py
│
├── tests/
│   └── __init__.py
│
├── pyproject.toml
└── README.md

Then, change the directory to your new project and add a few dependencies that you’ll rely on later:

$ cd digital-guitar/
$ poetry add numpy pedalboard pydantic pyyaml

After you run this command, Poetry will create an isolated virtual environment in a designated location for your project and install the listed third-party Python packages into it. You should also see a new poetry.lock file in your project’s root folder.

You can now open the digital-guitar/ folder in the Python IDE or code editor of your choice. If you use Visual Studio Code or PyCharm, then both programs will discover the virtual environment created by Poetry. The latter will also associate it with the project, letting you access the installed packages right away.

In VS Code, you may need to manually select the Poetry-managed virtual environment. To do this, bring up the Command Palette, type Python: Select Interpreter, and choose the desired interpreter. Conversely, after you open the folder in PyCharm, confirm the prompt asking you to set up a Poetry environment. The corresponding Python interpreter will appear in the bottom-right corner of the window.

Alternatively, if you’re a die-hard Vim or Sublime Text user, then you can continue to use Poetry in the command line:

$ poetry install
$ poetry run play-tab demo/tabs/doom.yaml
Saved file /home/user/digital-guitar/doom.mp3

The first command will install your project, along with its dependencies, defined in the pyproject.toml file. The second command, which you’ll implement later, will execute a script from within the associated virtual environment managed by Poetry. Note that you’ll use these commands anyway, regardless of which code editor you choose.

Embrace Immutable Data Types in Your Project

With only a few exceptions, you’ll define immutable data types almost exclusively in this project. Immutable objects are those that you can’t alter once you create them. While that may sound limiting at first, it actually brings a host of advantages. Therefore, it’s a good idea to familiarize yourself with the concept of immutability and its impact on your program’s behavior before you get started.

First of all, most immutable objects in Python are hashable, making them valid dictionary keys. Later, this will become essential for caching argument values to avoid repetitive computation. In the long run, it’ll help you reduce the overall time needed for sound synthesis.

Other than that, you can safely use immutable objects as default argument values without worrying about unintended side effects. In contrast, mutable default arguments are one of the most common pitfalls in Python, which can lead to surprising and difficult-to-track bugs. By sticking to immutable types where possible, you’ll save yourself a lot of headaches.

Also, you can think of immutable objects as simple values like integers or strings. When you assign an immutable variable to another variable, the assignment binds both references to the same object in memory. But, as soon as you attempt to modify the state of your immutable object through one of these variables, you’ll create a copy of that object, leaving the original one intact. Thus, your code becomes more predictable and resilient.

Immutable objects are also thread-safe and make it easier to reason about your code. These traits make them especially suitable for the functional programming paradigm, but you’ll enjoy their benefits in the object-oriented realm, too.

Now, it’s time to put this theory into practice by implementing your first immutable data type for this guitar synthesizer project.

Represent Time Instants, Durations, and Intervals

Music is an ephemeral form of art that you can only appreciate for a short period of time when it’s being played or performed. Because music inherently exists in time, it’s crucial that you’re able to properly represent time instants, durations, and intervals if you want to build a robust synthesizer.

Python’s float data type isn’t precise enough for musical timing due to the representation and rounding errors ingrained in the IEEE 754 standard. When you need greater precision, the recommended practice in Python is to replace floating-point numbers with either a Decimal or Fraction data type. However, using these types directly can be cumbersome, and they don’t carry the necessary information about the time units involved.

To alleviate these nuisances, you’ll implement a few custom classes, starting with the versatile Time data type. Go ahead and create a new Python module named temporal inside your digitar package, and define the following data class in it:

from dataclasses import dataclass
from decimal import Decimal
from fractions import Fraction
from typing import Self

type Numeric = int | float | Decimal | Fraction

@dataclass(frozen=True)
class Time:
    seconds: Decimal

    @classmethod
    def from_milliseconds(cls, milliseconds: Numeric) -> Self:
        return cls(Decimal(str(float(milliseconds))) / 1000)

This class has only one attribute, representing the number of seconds as a Decimal object for improved accuracy. You can create instances of your new class by providing the seconds through its constructor or by calling a class method that expects milliseconds and converts them to seconds wrapped in an appropriate data type.

from typing import TypeAlias

Numeric: TypeAlias = int | float | Decimal | Fraction

Due to Python’s dynamic nature, the default constructor generated by the interpreter for your data class won’t enforce type hints that you annotated your attributes with. In other words, the interpreter won’t verify whether the supplied values are of the expected types. So, in this case, if you pass an integer or a floating-point number instead of a Decimal object, then you’ll inadvertently create an instance with an incorrect attribute type.

Fortunately, you can prevent this issue by implementing your own initializer method in the class that will replace the one that Python generates by default:

from dataclasses import dataclass
from decimal import Decimal
from fractions import Fraction
from typing import Self

type Numeric = int | float | Decimal | Fraction

@dataclass(frozen=True)
class Time:
    seconds: Decimal

    @classmethod
    def from_milliseconds(cls, milliseconds: Numeric) -> Self:
        return cls(Decimal(str(float(milliseconds))) / 1000)

    def __init__(self, seconds: Numeric) -> None:
        match seconds:
            case int() | float():
                object.__setattr__(self, "seconds", Decimal(str(seconds)))
            case Decimal():
                object.__setattr__(self, "seconds", seconds)
            case Fraction():
                object.__setattr__(
                    self, "seconds", Decimal(str(float(seconds)))
                )
            case _:
                raise TypeError(
                    f"unsupported type '{type(seconds).__name__}'"
                )

You use structural pattern matching to detect the type of argument passed to your method at runtime and branch off accordingly. Then, you ensure that the instance attribute, .seconds, is always set to a Decimal object, regardless of the input type. If you pass a Decimal instance to your constructor, then there’s nothing more to do. Otherwise, you use the appropriate conversion or raise an exception to signal the misuse of the constructor.

Because you defined a frozen data class, which makes its instances immutable, you can’t set the attribute value directly or call the built-in setattr() function on an existing object. That would violate the immutability contract. If you ever need to forcefully change the state of a frozen data class instance, then you can resort to a hack by explicitly calling object.__setattr__(), as in the code snippet above.

You might recall that data classes support a special method for precisely this kind of customization. However, the advantage of overwriting the default initializer method instead of implementing .__post_init__() is that you take complete control of the object creation process. As a result, an object can either exist and be in a valid state or not exist at all.

Finally, you can implement a convenience method that you’ll use later for translating a duration in seconds into the corresponding number of audio samples:

from dataclasses import dataclass
from decimal import Decimal
from fractions import Fraction
from typing import Self

type Numeric = int | float | Decimal | Fraction
type Hertz = int | float

@dataclass(frozen=True)
class Time:
    # ...

    def get_num_samples(self, sampling_rate: Hertz) -> int:
        return round(self.seconds * round(sampling_rate))

This method takes a sampling rate in hertz (Hz) as an argument, which represents the number of samples per second. Multiplying the duration in seconds by the sampling rate in hertz yields the required number of samples, which you can round to return an integer.

Here’s a short Python REPL session demonstrating how you can take advantage of your new data class:

>>> from digitar.temporal import Time

>>> Time(seconds=0.15)
Time(seconds=Decimal('0.15'))

>>> Time.from_milliseconds(2)
Time(seconds=Decimal('0.002'))

>>> _.get_num_samples(sampling_rate=44100)
88

The underscore (_) in the REPL is an implicit variable that holds the value of the last evaluated expression. In this case, it refers to your Time instance representing two milliseconds.

With the Time class in place, you’re ready to move on to the next step. You’ll dip your toes into the physics of a vibrating string and see how it produces a sound.

Get to Know the Karplus-Strong Algorithm

The Karplus-Strong algorithm is surprisingly straightforward, given the complex sounds it can produce. In a nutshell, it starts by filling a very short buffer with a burst of random noise or another signal that has rich energy or many frequency components. That noise corresponds to the excitation of an actual string, which initially vibrates in several incoherent patterns of motion.

These seemingly random vibrations gradually become more and more sinusoidal, with a clear sine-like period and frequency that you perceive as a distinctive pitch. While the amplitudes of all vibrations weaken over time due to energy dissipation caused by internal friction and energy transfer, a certain fundamental frequency remains stronger than most of the overtones and harmonics that fade away more quickly.

The Karplus-Strong algorithm applies a low-pass filter to the signal to simulate the decay of higher frequencies at a faster pace than the fundamental frequency. It does so by calculating a moving average of two consecutive amplitude levels in the buffer, effectively acting as a bare-bones convolution filter. It removes the short-term fluctuations while leaving the longer-term trend.

Additionally, the algorithm feeds the averaged values back into the buffer to reinforce and continue the vibration, albeit with gradual energy loss. Take a look at the diagram below to have a better picture of how this positive feedback loop works:

The generator on the left serves as the input to the algorithm, providing the initial burst of noise. It’ll typically be white noise with a uniform probability distribution so that, on average, no particular frequency is emphasized over another. The analogy is similar to white light, which contains all frequencies of the visible spectrum at roughly equal intensities.

The generator shuts down after filling a circular buffer, also known as the delay line, which delays the signal by a certain amount of time before feeding it back to the loop. The phase-shifted signal from the past is then mixed with the current signal. Think of it as the wave’s reflection propagating along the string in the opposite direction.

The amount of delay determines the frequency of the virtual string’s vibration. Just like with the guitar’s string length, a shorter delay results in a higher pitch, while a longer delay produces a lower pitch. You can calculate the required size of the buffer—in terms of the number of audio samples—using the following formula:

To get the number of samples, D, multiply the vibration’s period or the reciprocal of the desired fundamental frequency, F₀, by your signal’s sampling frequency, F_s. Simply put, divide the sampling frequency by the fundamental frequency.

Then, the delayed signal goes through a low-pass filter before being added to the next sample from the buffer. You can implement both the filter and the adder by applying a weighted average to both samples as long as their weights sum to one or less. Otherwise, you’d be boosting the signal instead of attenuating it. By adjusting the weights, you can control the decay or damping of your virtual string’s vibration.

As the processed signal cycles through the buffer, it loses more high-frequency content and settles into a pattern that closely resembles the sound of a plucked string. Thanks to the feedback loop, you get the illusion of a vibrating string that gradually fades out.

Finally, on the far right of the diagram, you can see the output, which could be a loudspeaker or an audio file that you write the resulting audio samples to.

When you plot the waveforms and their corresponding frequency spectra from successive cycles of the feedback loop, you’ll observe the following pattern emerge:

The top graph shows amplitude oscillations over time. The graph just below it depicts the signal’s frequency content at specific moments. Initially, the buffer is filled with random samples, whose frequency distribution is roughly equal across the spectrum. As time goes by, the signal’s amplitude decreases, and the frequency of oscillations starts to concentrate at a particular spectral band. The shape of the waveform resembles a sine wave now.

Since you now understand the principles of the Karplus-Strong algorithm, you can implement the first element of the diagram shown earlier.

Use Random Values as the Initial Noise Burst

There are many kinds of signal generators that you can choose from in sound synthesis. Some of the most popular ones include periodic functions like the square wave, triangle wave, and sawtooth wave. However, in the Karplus-Strong synthesis algorithm, you’ll get the best results with an aperiodic function, such as random noise, due to its rich harmonic content that you can filter over time.

Noise comes in different colors, like pink or white. The difference lies in their spectral power density across frequencies. In white noise, for example, each frequency band has approximately the same power. So, it’s perfect for an initial noise burst because it contains a wide range of harmonics that you can shape through a filter.

To allow for experimenting with the different kinds of signal generators, you’ll define a custom protocol class in a new Python module named burst:

from typing import Protocol
import numpy as np
from digitar.temporal import Hertz

class BurstGenerator(Protocol):
    def __call__(self, num_samples: int, sampling_rate: Hertz) -> np.ndarray:
        ...

The point of a protocol class is to specify the desired behavior through method signatures without implementing those methods. In Python, you typically use an ellipsis (...) to indicate that you’ve intentionally left the method body undefined. Therefore, a protocol class acts like an interface in Java, where concrete classes implementing that particular interface provide the underlying logic.

In this case, you declared the special method .__call__()to make instances of classes that adhere to the protocol callable. Your method expects two arguments:

1. The number of audio samples to produce
2. The number of samples per second

Additionally, burst generators are meant to return a NumPy array of amplitude levels, which should be floating-point numbers normalized to an interval between minus one and plus one. Such normalization will make the subsequent audio processing more convenient.

Your first concrete generator class will produce white noise, as you’ve already established that it’s most appropriate in this context:

# ...

class WhiteNoise:
    def __call__(self, num_samples: int, sampling_rate: Hertz) -> np.ndarray:
        return np.random.uniform(-1.0, 1.0, num_samples)

Even though your new class doesn’t inherit from BurstGenerator, it still conforms to the protocol you defined earlier by providing a .__call__() method with the correct signature. Notice that the method takes the sampling rate as the second argument despite not referencing it anywhere in the body. That’s required to satisfy the protocol.

Instances of your WhiteNoise generator class are callable now:

>>> from digitar.burst import WhiteNoise

>>> burst_generator = WhiteNoise()
>>> samples = burst_generator(num_samples=1_000_000, sampling_rate=44100)

>>> samples.min()
-0.9999988055552775

>>> samples.max()
0.999999948864092

>>> samples.mean()
-0.0001278112173601203

The resulting samples are constrained to the range between -1 and 1, as the minimum and maximum values are very close to these bounds. Also, the mean value is near zero because, over a large number of samples, the positive and negative amplitudes balance each other out, confirming a uniform value distribution.

Okay. The next big component in the diagram of the Karplus-Strong algorithm is the feedback loop itself. You’re going to break it down into smaller pieces now.

Filter Higher Frequencies With a Feedback Loop

An elegant way to simulate a feedback loop in Python entails wiring generator functions together and sending values to them. You can also define asynchronous functions and hook them up as cooperative coroutines to achieve a similar effect. However, in this tutorial, you’ll use a much more straightforward and slightly more efficient implementation based on iteration.

Create another module named synthesis in your Python package and define the following class placeholder:

from dataclasses import dataclass
from digitar.burst import BurstGenerator, WhiteNoise

AUDIO_CD_SAMPLING_RATE = 44100

@dataclass(frozen=True)
class Synthesizer:
    burst_generator: BurstGenerator = WhiteNoise()
    sampling_rate: int = AUDIO_CD_SAMPLING_RATE

This frozen data class consists of two optional attributes, which let you specify the expected burst generator implementation and the sampling rate. If you skip those parameters when creating a new instance of the class, then you’ll rely on the defaults, which use the white noise generator at a 44.1 kHz sampling rate defined as a Python constant.

Using the standard-library itertools package, you can now implement an infinite iterator that will cycle() through the buffer of audio samples. The following code snippet mirrors the Karplus-Strong diagram that you saw in an earlier section:

from dataclasses import dataclass
from itertools import cycle
from typing import Iterator

import numpy as np

from digitar.burst import BurstGenerator, WhiteNoise
from digitar.temporal import Hertz, Time

AUDIO_CD_SAMPLING_RATE = 44100

@dataclass(frozen=True)
class Synthesizer:
    burst_generator: BurstGenerator = WhiteNoise()
    sampling_rate: int = AUDIO_CD_SAMPLING_RATE

    def vibrate(
        self, frequency: Hertz, duration: Time, damping: float = 0.5
    ) -> np.ndarray:
        assert 0 < damping <= 0.5

        def feedback_loop() -> Iterator[float]:
            buffer = self.burst_generator(
                num_samples=round(self.sampling_rate / frequency),
                sampling_rate=self.sampling_rate
            )
            for i in cycle(range(buffer.size)):
                yield (current_sample := buffer[i])
                next_sample = buffer[(i + 1) % buffer.size]
                buffer[i] = (current_sample + next_sample) * damping

You define the .vibrate() method that takes the vibration’s fundamental frequency, duration, and an optional damping coefficient as arguments. When left unspecified, the coefficient’s default value halves the sum of two adjacent samples with each cycle, which is analogous to computing a moving average. It simulates energy loss as the vibration fades out.

So far, your method defines an inner function that returns a generator iterator when called. The resulting generator object allocates and fills a buffer using the provided burst generator. The function then enters an infinite for loop that keeps yielding values from the buffer indefinitely in a round-robin fashion because it has no stopping condition.

You use the Walrus operator (:=) to simultaneously yield and intercept the current amplitude value in each cycle. On the next iteration, you calculate the average of the two adjacent values to simulate the damping effect. The modulo operator (%) ensures that the index wraps around to the beginning of the buffer once it reaches the end, creating a circular buffer effect.

To consume a finite number of samples determined by the duration parameter, you can wrap your feedback_loop() with a call to NumPy’s fromiter() function:

# ...

@dataclass(frozen=True)
class Synthesizer:
    # ...

    def vibrate(
        self, frequency: Hertz, duration: Time, damping: float = 0.5
    ) -> np.ndarray:
        assert 0 < damping <= 0.5

        def feedback_loop() -> Iterator[float]:
            buffer = self.burst_generator(
                num_samples=round(self.sampling_rate / frequency),
                sampling_rate=self.sampling_rate
            )
            for i in cycle(range(buffer.size)):
                yield (current_sample := buffer[i])
                next_sample = buffer[(i + 1) % buffer.size]
                buffer[i] = (current_sample + next_sample) * damping

        return np.fromiter(
            feedback_loop(),
            np.float64,
            duration.get_num_samples(self.sampling_rate),
        )

As long as the duration parameter is an instance of the Time data class that you defined earlier, you can convert the number of seconds into the corresponding number of audio samples by calling .get_num_samples(). Just remember to pass the correct sampling rate. You should also specify float64 as the data type for the elements of your NumPy array to ensure high precision and avoid unnecessary type conversions.

You’re almost done implementing the Karplus-Strong synthesis algorithm, but your code has two minor issues that you need to address first.

Remove the DC Bias and Normalize Audio Samples

Depending on the initial burst and the damping coefficient, you may end up with values outside the expected amplitude range, or the values may drift away from zero, introducing a DC bias. That could result in audible clicks or other unpleasant artifacts. To fix these potential problems, you’ll remove the bias by subtracting the signal’s mean value, and you’ll normalize the resulting samples afterward.

NumPy doesn’t provide built-in functions for these tasks, but making your own isn’t too complicated. Start by creating a new module named processing in your package with these two functions:

import numpy as np

def remove_dc(samples: np.ndarray) -> np.ndarray:
    return samples - samples.mean()

def normalize(samples: np.ndarray) -> np.ndarray:
    return samples / np.abs(samples).max()

Both functions take advantage of NumPy’s vectorization capabilities. The first one subtracts the mean value from each element, and the second divides all samples by the maximum absolute value in the input array.

Now, you can import and call your helper functions in the synthesizer before returning the array of computed audio samples:

from dataclasses import dataclass
from itertools import cycle
from typing import Iterator

import numpy as np

from digitar.burst import BurstGenerator, WhiteNoise
from digitar.processing import normalize, remove_dc
from digitar.temporal import Hertz, Time

AUDIO_CD_SAMPLING_RATE = 44100

@dataclass(frozen=True)
class Synthesizer:
    # ...

    def vibrate(
        self, frequency: Hertz, duration: Time, damping: float = 0.5
    ) -> np.ndarray:
        # ...
        return normalize(
            remove_dc(
                np.fromiter(
                    feedback_loop(),
                    np.float64,
                    duration.get_num_samples(self.sampling_rate),
                )
            )
        )

Although the order may not make a significant difference, it’s customary to remove the DC bias before performing the normalization. Removing the DC component ensures that your signal is centered around zero. Otherwise, it might still have a DC component, which could affect the overall scale of the normalization.

Great! You’ve just implemented the Karplus-Strong synthesis algorithm in Python. Why not put it to the test to hear the results?

Pluck the String to Produce Monophonic Sounds

Strictly speaking, your synthesizer returns a NumPy array of normalized amplitude levels instead of audio samples directly corresponding to digital sound. At the same time, you can choose from several data formats, compression schemes, and encodings to determine how to store and transmit your audio data.

For example, Linear Pulse-Code Modulation (LPCM) is a standard encoding in uncompressed WAV files, which typically use 16-bit signed integers to represent audio samples. Other formats like MP3 employ lossy compression algorithms that reduce file size by removing information that’s less perceivable by the human ear. These formats can offer constant or variable bitrates depending on the desired quality and file size.

To avoid getting bogged down by the technicalities, you’ll use Spotify’s Pedalboard library, which can handle these low-level details for you. You’ll supply the normalized amplitude levels from your synthesizer, and Pedalboard will encode them accordingly depending on your preferred data format:

>>> from pedalboard.io import AudioFile

>>> from digitar.synthesis import Synthesizer
>>> from digitar.temporal import Time

>>> frequencies = [261.63, 293.66, 329.63, 349.23, 392, 440, 493.88, 523.25]
>>> duration = Time(seconds=0.5)
>>> damping = 0.495

>>> synthesizer = Synthesizer()
>>> with AudioFile("monophonic.mp3", "w", synthesizer.sampling_rate) as file:
...     for frequency in frequencies:
...         file.write(synthesizer.vibrate(frequency, duration, damping))

In this case, you save the synthesized sounds as an MP3 file using the library’s default parameters. The code snippet above produces an MP3 file with a mono channel sampled at 44.1 kHz and a constant bitrate of 320 kilobits per second, which is the highest quality supported by this format. Remember to run the code from within your project’s virtual environment to access the required modules.

To confirm some of these audio properties, you can open the file for reading and check a few of its attributes:

>>> with AudioFile("monophonic.mp3") as file:
...     print(f"{file.num_channels = }")
...     print(f"{file.samplerate = }")
...     print(f"{file.file_dtype = }")
...
file.num_channels = 1
file.samplerate = 44100
file.file_dtype = 'float32'

Because MP3 files are compressed, you can’t calculate their bitrate from these parameters. The actual bitrate is stored in the file’s header along with other metadata, which you can verify using an external program like MediaInfo:

$ mediainfo monophonic.mp3
General
Complete name                            : monophonic.mp3
Format                                   : MPEG Audio
File size                                : 159 KiB
Duration                                 : 4 s 48 ms
Overall bit rate mode                    : Constant
Overall bit rate                         : 320 kb/s
Writing library                          : LAME3.100
(...)

The generated file contains a series of musical tones based on the frequencies that you supplied. Each tone is sustained for half a second, resulting in a melody that progresses through the notes do-re-mi-fa-sol-la-ti-do. These tones are the solfeggio notes, often used to teach the musical scale. Below is what they look like when plotted as a waveform. You can click the play button to take a listen:

Notice that each tone stops abruptly before getting a chance to fade out completely. You can experiment with a longer or shorter duration and adjust the the damping parameter. But, no matter how hard you try, you can only produce monophonic sounds without the possibility of overlaying multiple notes.

In the next section, you’ll learn how to synthesize more complex sounds, getting one step closer to simulating a full-fledged guitar.

Blend Multiple Notes Into a Polyphonic Sound

To play multiple notes simultaneously, you can mix the corresponding acoustic waves. Go ahead and define another method in your synthesizer class, which will be responsible for overlaying samples from multiple sounds on top of each other:

from dataclasses import dataclass
from itertools import cycle
from typing import Iterator, Sequence

# ...

@dataclass(frozen=True)
class Synthesizer:
    # ...

    def overlay(self, sounds: Sequence[np.ndarray]) -> np.ndarray:
        return np.sum(sounds, axis=0)

This method takes a sequence of equal-sized NumPy arrays comprising the amplitudes of several sounds to mix. The method then returns the element-wise arithmetic sum of the input sound waves.

Assuming you’ve already removed the DC bias from the individual sounds you want to mix, you no longer need to worry about it. Additionally, you don’t want to normalize the overlaid sounds at this stage because their number may vary greatly within a single song. Doing so now could lead to inconsistent volume levels, making certain musical chords barely audible. Instead, you must apply normalization before writing the entire song into the file.

Suppose you wanted to simulate a performer plucking all the strings of a guitar at the same time. Here’s how you could do that using your new method:

>>> from pedalboard.io import AudioFile

>>> from digitar.processing import normalize
>>> from digitar.synthesis import Synthesizer
>>> from digitar.temporal import Time

>>> frequencies = [329.63, 246.94, 196.00, 146.83, 110.00, 82.41]
>>> duration = Time(seconds=3.5)
>>> damping = 0.499

>>> synthesizer = Synthesizer()
>>> sounds = [
...     synthesizer.vibrate(frequency, duration, damping)
...     for frequency in frequencies
... ]

>>> with AudioFile("polyphonic.mp3", "w", synthesizer.sampling_rate) as file:
...     file.write(normalize(synthesizer.overlay(sounds)))

You define the frequencies corresponding to the standard tuning of a six-string guitar and set the duration of an individual note to three and a half seconds. Additionally, you adjust the damping coefficient to a slightly greater value than before to make it vibrate longer. Then, you synthesize each string’s sound in a list comprehension and combine them using your .overlay() method.

This will be the resulting waveform of the audio file that you’ll create after you run the code listed above:

It’s unquestionably an improvement over the monophonic version. However, the synthesized file still sounds a bit artificial when you play it. That’s because, with a real guitar, the strings are never plucked at precisely the same moment. There’s always a slight delay between each string being plucked. The resulting wave interactions create complex resonances, adding to the richness and authenticity of the sound.

Next, you’ll introduce an adjustable delay between the subsequent strokes to give your polyphonic sound a more realistic feel. You’ll be able to discern the striking direction as a result of that!

Adjust the Stroke Speed to Control the Rhythm

When you stroke the strings of a guitar quickly, the delay between successive plucks is relatively short, making the overall sound loud and sharp. Conversely, the delay increases as you pluck the strings more slowly and gently. You can take this technique to the extreme by playing an arpeggio or a broken chord where you play the notes one after the other rather than simultaneously.

Now, modify your .overlay() method so that it accepts an additional delay parameter representing the time interval between each stroke:

# ...

@dataclass(frozen=True)
class Synthesizer:
    # ...

    def overlay(
        self, sounds: Sequence[np.ndarray], delay: Time
    ) -> np.ndarray:
        num_delay_samples = delay.get_num_samples(self.sampling_rate)
        num_samples = max(
            i * num_delay_samples + sound.size
            for i, sound in enumerate(sounds)
        )
        samples = np.zeros(num_samples, dtype=np.float64)
        for i, sound in enumerate(sounds):
            offset = i * num_delay_samples
            samples[offset : offset + sound.size] += sound
        return samples

Based on the current sampling frequency of your synthesizer, you convert the delay in seconds into the corresponding number of samples. Then, you find the total number of samples to allocate for the resulting array, which you initialize with zeros. Finally, you iterate over the sounds, adding them into your samples array with the appropriate offset.

Here’s the same example you saw in the previous section. However, you now have a forty-millisecond delay between the individual plucks, and you vary the vibration duration depending on its frequency:

>>> from pedalboard.io import AudioFile

>>> from digitar.processing import normalize
>>> from digitar.synthesis import Synthesizer
>>> from digitar.temporal import Time

>>> frequencies = [329.63, 246.94, 196.00, 146.83, 110.00, 82.41]
>>> delay = Time.from_milliseconds(40)
>>> damping = 0.499

>>> synthesizer = Synthesizer()
>>> sounds = [
...     synthesizer.vibrate(frequency, Time(3.5 + 0.25 * i), damping)
...     for i, frequency in enumerate(frequencies)
... ]

>>> with AudioFile("arpeggio.mp3", "w", synthesizer.sampling_rate) as file:
...     file.write(normalize(synthesizer.overlay(sounds, delay)))

Notes with a lower frequency will have a slightly longer duration than their higher-frequency counterparts. This simulates the inertia of real strings, which tend to vibrate longer if they are thicker or longer.

Below is the corresponding waveform, which appears to have more variation and complexity:

If you look closely at this waveform, then you’ll see the individual peaks at the beginning, indicating where the subsequent notes start. They’re equally spaced, as determined by your delay parameter.

By changing the delay, you can adjust the stroke speed to create a faster and more dynamic rhythm or a slower, more mellow sound. You’ll use this parameter to enhance the expressiveness of your virtual instrument and mimic the musical phrasings that a guitarist might naturally use.

Now that you have control over the timing of each note in a chord, you can experiment further by changing the order in which you play them.

Reverse the Strumming Direction to Alter the Timbre

Guitarists often vary not just the speed but also the strumming direction as they play. By alternating between downstrokes and upstrokes, they can emphasize different strings and change the timbre of the same chord. Downstrokes tend to sound more powerful and are usually louder because the pick—or your finger—hits the lower, thicker strings first. Conversely, upstrokes often highlight the higher, thinner strings, producing a lighter sound.

You can express both the strumming speed and direction with custom data types. Create a Python module named stroke in your digitar package and define these two classes in it:

import enum
from dataclasses import dataclass
from typing import Self

from digitar.temporal import Time

class Direction(enum.Enum):
    DOWN = enum.auto()
    UP = enum.auto()

@dataclass(frozen=True)
class Velocity:
    direction: Direction
    delay: Time

    @classmethod
    def down(cls, delay: Time) -> Self:
        return cls(Direction.DOWN, delay)

    @classmethod
    def up(cls, delay: Time) -> Self:
        return cls(Direction.UP, delay)

The first class is a Python enumeration, which assigns unique values to the mutually exclusive stroke directions, of which there are two. The following class, Velocity, uses that enumeration as its member, combining it with the delay or the interval between the subsequent plucks.

You can quickly instantiate objects to represent guitar strokes by calling convenient class methods on your Velocity class:

>>> from digitar.stroke import Direction, Velocity
>>> from digitar.temporal import Time

>>> slow = Time.from_milliseconds(40)
>>> fast = Time.from_milliseconds(20)

>>> Velocity.down(slow)
Velocity(direction=<Direction.DOWN: 1>, delay=Time(seconds=Decimal('0.04')))

>>> Velocity.up(fast)
Velocity(direction=<Direction.UP: 2>, delay=Time(seconds=Decimal('0.02')))

The first stroke is slow and directed downward, while the second is faster and directed upward. You’ll use these new data types in the project to control the musical feel of your digital guitar.

But there are many kinds of guitars in the wild. Some have fewer strings, others are bigger or smaller, and some need an electronic amplifier. On top of that, you can tune each instrument to different notes. So, before you can properly take advantage of the stroke velocity, you need to build a virtual instrument and learn how to handle it.

Press a Vibrating String to Change Its Pitch

Most guitars have between four and twelve strings, each capable of producing a variety of pitches. When you pluck an open string without touching the guitar neck, the string starts to vibrate at its fundamental frequency. However, once you press the string against one of the metal strips or frets along the fingerboard, you effectively shorten the string, changing its vibration frequency when plucked.

Each guitar fret represents an increase in pitch by a single semitone or a half-step on the chromatic scale—the standard scale in Western music. The chromatic scale divides each octave, or a set of eight musical notes, into twelve equally spaced semitones, with a ratio of the twelfth root of two between them. When you go all the way up to the twelfth semitone, you’ll double the frequency of the note that marks the beginning of an octave.

The distances between adjacent frets in a fretted instrument follow the same principle, reflecting the logarithmic nature of the frequency increase at each step. As you move along the fretboard and press down on successive frets, you’ll notice the pitch of the string progressively increasing, one semitone at a time.

On a typical six-string guitar, you’ll usually find about twenty or more frets, amounting to over a hundred pitches! However, when you account for the duplicates due to overlapping octaves, the actual number of distinctive pitches decreases. In reality, you can play about four octaves of musical notes, which is short of fifty unique pitches. On the other hand, the virtual guitar that you’re about to build has no such limits!

In Python, you can implement a semitone-based pitch adjustment like this:

from dataclasses import dataclass
from typing import Self

from digitar.temporal import Hertz

@dataclass(frozen=True)
class Pitch:
    frequency: Hertz

    def adjust(self, num_semitones: int) -> Self:
        return Pitch(self.frequency * 2 ** (num_semitones / 12))

Once you create a new pitch, you can modify the corresponding fundamental frequency by calling .adjust() with the desired number of semitones. A positive number of semitones will increase the frequency, a negative number will decrease it, while zero will keep it intact. Note that you use Python’s exponentiation operator (**) to calculate the twelfth root of two, which the formula relies on.

To confirm that your code is working as expected, you can run the following test:

>>> from digitar.pitch import Pitch

>>> pitch = Pitch(frequency=110.0)
>>> semitones = [-12, 12, 24] + list(range(12))

>>> for num_semitones in sorted(semitones):
...     print(f"{num_semitones:>3}: {pitch.adjust(num_semitones)}")
...
-12: Pitch(frequency=55.0)
  0: Pitch(frequency=110.0)
  1: Pitch(frequency=116.54094037952248)
  2: Pitch(frequency=123.47082531403103)
  3: Pitch(frequency=130.8127826502993)
  4: Pitch(frequency=138.59131548843604)
  5: Pitch(frequency=146.8323839587038)
  6: Pitch(frequency=155.56349186104046)
  7: Pitch(frequency=164.81377845643496)
  8: Pitch(frequency=174.61411571650194)
  9: Pitch(frequency=184.9972113558172)
 10: Pitch(frequency=195.99771799087463)
 11: Pitch(frequency=207.65234878997256)
 12: Pitch(frequency=220.0)
 24: Pitch(frequency=440.0)

You start by defining a pitch produced by a string vibrating at 110 Hz, which corresponds to the A note in the second octave. Then, you iterate over a list of semitone numbers to adjust the pitch accordingly.

Depending on whether the given number is negative or positive, adjusting the frequency by exactly twelve semitones (one octave) either halves or doubles the original frequency of that pitch. Anything in between sets the frequency to the corresponding semitone within that octave.

Being able to adjust the frequency is useful, but the Pitch class forces you to think in terms of pitches, semitones, and octaves, which isn’t the most convenient. You’ll wrap the pitch in a higher-level class inside a new module named instrument:

from dataclasses import dataclass

from digitar.pitch import Pitch

@dataclass(frozen=True)
class VibratingString:
    pitch: Pitch

    def press_fret(self, fret_number: int | None = None) -> Pitch:
        if fret_number is None:
            return self.pitch
        return self.pitch.adjust(fret_number)

To simulate plucking an open string, pass None or leave the fret_number parameter out when calling your .press_fret() method. By doing so, you’ll return the string’s unaltered pitch. Alternatively, you can pass zero as the fret number.

And here’s how you can interact with your new class:

>>> from digitar.instrument import VibratingString
>>> from digitar.pitch import Pitch

>>> a2_string = VibratingString(Pitch(frequency=110))

>>> a2_string.pitch
Pitch(frequency=110)

>>> a2_string.press_fret(None)
Pitch(frequency=110)

>>> a2_string.press_fret(0)
Pitch(frequency=110.0)

>>> a2_string.press_fret(1)
Pitch(frequency=116.54094037952248)

>>> a2_string.press_fret(12)
Pitch(frequency=220.0)

You can now treat pitches and guitar strings independently, which lets you assign a different pitch to the same string if you want to. This mapping of pitches to open strings is known as guitar tuning in music. Tuning systems require you to understand a specific notation of musical notes, which you’ll learn about in the next section.

Read Musical Notes From Scientific Pitch Notation

In scientific pitch notation, every musical note appears as a letter followed by an optional symbol, such as a sharp (♯) or flat (♭) denoting accidentals, as well as an octave number. The sharp symbol raises the note’s pitch by a semitone, while the flat symbol lowers it by a semitone. If you omit the octave number, then zero is assumed implicitly.

There are seven letters in this notation, with C marking the boundaries of each octave:

In this case, you’re looking at the first octave comprising eight notes: C₀, D₀, E₀, F₀, G₀, A₀, B₀, and C₁. The system starts at C₀ or just C, which is approximately 16.3516 Hz. When you go all the way up to C₁ on the right, which also starts the next octave, you’ll double that frequency.

Note: While most letters are a whole tone apart, not all of them have sharp or flat equivalents. The letters E and F, as well as B and C, are already one half-tone apart, so there’s no E♯ or F♭. This is for historical reasons due to the technical limitations of the early piano keyboards:

When you overlay the notes in scientific pitch notation on top of a piano keyboard, you’ll notice that accidentals correspond to the five black keys. Conversely, the natural tones correspond to the seven white keys in each octave that repeat in both directions across the keyboard.

You can now decipher scientific pitch notation. For example, A₄ indicates the musical note A in the fourth octave, with a frequency of 440 Hz, which is the concert pitch reference. Similarly, C♯₄ represents the C-sharp note in the fourth octave, located one semitone above the middle C on a standard piano keyboard.

In Python, you can leverage regular expressions to programmatically translate this notation into numeric pitches. Add the following class method to the Pitch class in the pitch module:

import re
from dataclasses import dataclass
from typing import Self

from digitar.temporal import Hertz

@dataclass(frozen=True)
class Pitch:
    frequency: Hertz

    @classmethod
    def from_scientific_notation(cls, notation: str) -> Self:
        if match := re.fullmatch(r"([A-G]#?)(-?\d+)?", notation):
            note = match.group(1)
            octave = int(match.group(2) or 0)
            semitones = "C C# D D# E F F# G G# A A# B".split()
            index = octave * 12 + semitones.index(note) - 57
            return cls(frequency=440.0 * 2 ** (index / 12))
        else:
            raise ValueError(
                f"Invalid scientific pitch notation: {notation}"
            )

    def adjust(self, num_semitones: int) -> Self:
        return Pitch(self.frequency * 2 ** (num_semitones / 12))

This method calculates the frequency for a given note based on its distance in semitones from A₄. Note that this is a simplified implementation, which only takes sharp notes into account. If you need to represent a flat note, then you can rewrite it in terms of its equivalent sharp note, provided that it exists. For instance, B♭ is the same as A♯.

Here’s the sample usage of your new class method:

>>> from digitar.pitch import Pitch
>>> for note in "C", "C0", "A#", "C#4", "A4":
...     print(f"{note:>3}", Pitch.from_scientific_notation(note))
...
  C Pitch(frequency=16.351597831287414)
 C0 Pitch(frequency=16.351597831287414)
 A# Pitch(frequency=29.13523509488062)
C#4 Pitch(frequency=277.1826309768721)
 A4 Pitch(frequency=440.0)

As you can see, the code accepts and interprets a few variants of scientific pitch notation. That’s perfect! You’re now ready to tune up your digital guitar.

Perform String Tuning of the Virtual Guitar

In the real world, musicians adjust the tension of guitar strings by tightening or loosening the respective tuning pegs to achieve a perfectly tuned sound. Doing so allows them to assign different sets of musical notes or pitches to their instrument’s strings. They’ll occasionally reuse the same pitch for two or more strings to create a fuller sound.

Depending on the number of strings in a guitar, you’ll assign the musical notes differently. Apart from the standard tuning, which is the most typical choice of notes for a given instrument, you can apply several alternative guitar tunings, even when you have the same number of strings at your disposal.

The traditional six-string guitar tuning, from the thinnest string (highest pitch) to thickest one (lowest pitch), is the following:

If you’re right-handed, you’d typically use your right hand to strum or pluck the strings near the sound hole while your left hand frets the notes on the neck. In this orientation, the first string (E4) is closest to the bottom, while the sixth string (E2) is closest to the top.

It’s customary to denote guitar tunings in ascending frequency order. For example, the standard guitar tuning is usually presented as: E₂-A₂-D₃-G₃-B₃-E₄. At the same time, some guitar tabs follow the string numbering depicted in the table above, which reverses this order. Therefore, the top line in a six-string guitar tablature will usually represent the first string (E4) and the bottom line the sixth string (E2).

To avoid confusion, you’ll respect both conventions. Add the following class to your instrument module so that you can represent a string tuning:

from dataclasses import dataclass
from typing import Self

from digitar.pitch import Pitch

# ...

@dataclass(frozen=True)
class StringTuning:
    strings: tuple[VibratingString, ...]

    @classmethod
    def from_notes(cls, *notes: str) -> Self:
        return cls(
            tuple(
                VibratingString(Pitch.from_scientific_notation(note))
                for note in reversed(notes)
            )
        )

An object of this class contains a tuple of VibratingString instances sorted by the string number in ascending order. In other words, the first element in the tuple corresponds to the first string (E4) and the last element to the sixth string (E2). Note that the number of strings can be less than or greater than six should you need to represent other types of stringed instruments, such as a banjo, which has just five strings.

In practice, you’ll create new instances of the StringTuning class by calling the .from_notes() class method and passing a variable number of musical notes in scientific pitch notation. When you do, you must follow the string tuning order, starting with the lowest pitch. This is because the method reverses the input notes to match the typical string arrangement on a guitar tab.

Here’s how you might use the StringTuning class to represent various tuning systems for different plucked string instruments:

>>> from digitar.instrument import StringTuning

>>> StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4")
StringTuning(
    strings=(
        VibratingString(pitch=Pitch(frequency=329.6275569128699)),
        VibratingString(pitch=Pitch(frequency=246.94165062806206)),
        VibratingString(pitch=Pitch(frequency=195.99771799087463)),
        VibratingString(pitch=Pitch(frequency=146.8323839587038)),
        VibratingString(pitch=Pitch(frequency=110.0)),
        VibratingString(pitch=Pitch(frequency=82.4068892282175)),
    )
)

>>> StringTuning.from_notes("E1", "A1", "D2", "G2")
StringTuning(
  strings=(
    VibratingString(pitch=Pitch(frequency=97.99885899543733)),
    VibratingString(pitch=Pitch(frequency=73.41619197935188)),
    VibratingString(pitch=Pitch(frequency=55.0)),
    VibratingString(pitch=Pitch(frequency=41.20344461410875)),
  )
)

The first object represents the standard six-string guitar tuning, while the second one represents the four-string bass guitar tuning. You can use the same approach to model the tuning of other stringed instruments by providing the appropriate notes for each string.

With this, you can achieve the effect of fretting the guitar with your fingers to play a particular chord:

>>> tuning = StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4")
>>> frets = (None, None, 2, None, 0, None)
>>> for string, fret_number in zip(tuning.strings, frets):
...     if fret_number is not None:
...         string.press_fret(fret_number)
...
Pitch(frequency=220.0)
Pitch(frequency=110.0)

In this case, you use the standard guitar tuning. Then, you simulate pressing the second fret on the third string (G₃) and leaving the fifth string (A₂) open while strumming both of them. You don’t stroke or fret the remaining strings, as indicated by None in the tuple. The zip() function combines strings and the corresponding fret numbers into pairs that you iterate over.

The third string is tuned to note G₃ or 196 Hz. But, since you press it on the second fret, you increase its pitch by two semitones, resulting in a frequency of 220 Hz. The fifth string is tuned to A₂ or 110 Hz, which you play open or without fretting. When you mix both frequencies, you’ll produce a chord consisting of notes A₃ and A₂, which are one octave apart.

Next up, you’ll create a custom data type to represent musical chords more conveniently.

Represent Chords on a Fretted Instrument

Previously, you defined a plain tuple to express the fret numbers in a particular chord. You can be a tad bit more explicit by extending the tuple class and restricting the types of values that are allowed in it:

from typing import Self

class Chord(tuple[int | None, ...]):
    @classmethod
    def from_numbers(cls, *numbers: int | None) -> Self:
        return cls(numbers)

With type hints, you declare that your tuple should only contain integers representing the fret numbers or empty values (None) indicating an open string. You also provide a class method, .from_numbers(), allowing you to create a Chord instance by passing in the fret numbers directly. This method takes a variable number of arguments, each of which can be an integer or None.

Here’s how you might define a chord from the previous section of this tutorial using the Chord class:

>>> from digitar.chord import Chord

>>> Chord.from_numbers(None, None, 2, None, 0, None)
(None, None, 2, None, 0, None)

>>> Chord([None, None, 2, None, 0, None])
(None, None, 2, None, 0, None)

When you create a Chord instance using the class method, you pass the fret numbers as arguments. You can also instantiate the class by passing an iterable object of values, such as a list, to the constructor. However, it’s generally more explicit to use the .from_numbers() method.

To sum up, these are the most important points to remember:

• The value’s position in the tuple determines the string number, so the first element corresponds to the highest pitch.
• An empty value (None) means that you don’t pluck the string at all.
• Zero represents an open string, which you pluck without pressing any frets.
• Other integers correspond to fret numbers on a guitar neck that you press.

These are also finger patterns on guitar tabs that you’ll leverage later in the tutorial. Now, it’s time to define another custom data type with which you’ll represent different kinds of plucked string instruments in code.

Model Any Plucked String Instrument

When you think about the primary properties that influence how a plucked string instrument sounds, they’re the number of strings, their tuning, and the material they’re made of. While not the only one, the latter aspect affects how long the string will sustain its vibration and the degree of energy damping.

You can conveniently express those attributes by defining a data class in your instrument module:

from dataclasses import dataclass
from typing import Self

from digitar.pitch import Pitch
from digitar.temporal import Time

# ...

@dataclass(frozen=True)
class PluckedStringInstrument:
    tuning: StringTuning
    vibration: Time
    damping: float = 0.5

    def __post_init__(self) -> None:
        if not (0 < self.damping <= 0.5):
            raise ValueError(
                "string damping must be in the range of (0, 0.5]"
            )

The string tuning determines how many strings an instrument has and what their fundamental frequencies of vibration are. For simplicity, all strings in an instrument will share the same vibration time and damping coefficient that defaults to one-half. If you’d like to override them individually on a string-by-string basis, then you’ll need to tweak the code yourself.

The .__post_init__() method verifies whether the damping is within the acceptable range of values.

You can define a convenient property in your class to quickly find out the number of strings in an instrument without reaching out for the tuning object:

from dataclasses import dataclass
from functools import cached_property
from typing import Self

from digitar.pitch import Pitch
from digitar.temporal import Time

# ...

@dataclass(frozen=True)
class PluckedStringInstrument:
    # ...

    @cached_property
    def num_strings(self) -> int:
        return len(self.tuning.strings)

It’s a cached property for more efficient access. After you access such a property for the first time, Python remembers the computed value, so subsequent accesses won’t recompute it since the value doesn’t change during an object’s lifetime.

Next, you may add methods that will take a Chord instance, which you built earlier, and turn it into a tuple of pitches that you can later use to synthesize a polyphonic sound:

from dataclasses import dataclass
from functools import cache, cached_property
from typing import Self

from digitar.chord import Chord
from digitar.pitch import Pitch
from digitar.temporal import Time

# ...

@dataclass(frozen=True)
class PluckedStringInstrument:
    # ...

    @cache
    def downstroke(self, chord: Chord) -> tuple[Pitch, ...]:
        return tuple(reversed(self.upstroke(chord)))

    @cache
    def upstroke(self, chord: Chord) -> tuple[Pitch, ...]:
        if len(chord) != self.num_strings:
            raise ValueError(
                "chord and instrument must have the same string count"
            )
        return tuple(
            string.press_fret(fret_number)
            for string, fret_number in zip(self.tuning.strings, chord)
            if fret_number is not None
        )

Since the order of fret numbers in a chord agrees with the order of guitar strings (bottom-up), stroking a chord simulates an upstroke. Your .upstroke() method uses a generator expression with a conditional expression, which looks almost identical to the loop you saw earlier when you performed the string tuning. The .downstroke() method delegates execution to .upstroke(), intercepts the resulting tuple of the Pitch objects, and reverses it.

Because most chords repeat over and over again in similar patterns within a single song, you don’t want to calculate each one of them every time. Instead, you annotate both methods with the @cache decorator to avoid redundant computations. By storing the computed tuples, Python will return the cached result when the same inputs occur again.

You can now model different types of plucked string instruments to reproduce their unique acoustic characteristics. Here are a few examples using the standard tuning of each instrument:

>>> from digitar.instrument import PluckedStringInstrument, StringTuning
>>> from digitar.temporal import Time

>>> acoustic_guitar = PluckedStringInstrument(
...     tuning=StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4"),
...     vibration=Time(seconds=10),
...     damping=0.498,
... )

>>> bass_guitar = PluckedStringInstrument(
...     tuning=StringTuning.from_notes("E1", "A1", "D2", "G2"),
...     vibration=Time(seconds=10),
...     damping=0.4965,
... )

>>> electric_guitar = PluckedStringInstrument(
...     tuning=StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4"),
...     vibration=Time(seconds=0.09),
...     damping=0.475,
... )

>>> banjo = PluckedStringInstrument(
...     tuning=StringTuning.from_notes("G4", "D3", "G3", "B3", "D4"),
...     vibration=Time(seconds=2.5),
...     damping=0.4965,
... )

>>> ukulele = PluckedStringInstrument(
...     tuning=StringTuning.from_notes("A4", "E4", "C4", "G4"),
...     vibration=Time(seconds=5.0),
...     damping=0.498,
... )

Right now, they’re only abstract containers for logically related data. Before you can take full advantage of these virtual instruments and actually hear them, you must integrate them into your Karplus-Strong synthesizer, which you’ll do next.

Combine the Synthesizer With an Instrument

You want to parameterize your synthesizer with a plucked string instrument so that you can synthesize sounds that are characteristic of that particular instrument. Open the synthesis module in your Python project now and add an instrument field to the Synthesizer class:

from dataclasses import dataclass
from itertools import cycle
from typing import Sequence

import numpy as np

from digitar.burst import BurstGenerator, WhiteNoise
from digitar.instrument import PluckedStringInstrument
from digitar.processing import normalize, remove_dc
from digitar.temporal import Hertz, Time

AUDIO_CD_SAMPLING_RATE = 44100

@dataclass(frozen=True)
class Synthesizer:
    instrument: PluckedStringInstrument
    burst_generator: BurstGenerator = WhiteNoise()
    sampling_rate: int = AUDIO_CD_SAMPLING_RATE

    # ...

By using the properties defined in the PluckedStringInstrument class, the synthesizer can generate sounds that mimic the timbre and expression of a plucked string instrument, such as an acoustic guitar or a banjo.

Now that you have an instrument in your synthesizer, you can leverage its tuned strings to play a chord with the given speed and direction:

# ...

from digitar.burst import BurstGenerator, WhiteNoise
from digitar.chord import Chord
from digitar.instrument import PluckedStringInstrument
from digitar.processing import normalize, remove_dc
from digitar.stroke import Direction, Velocity
from digitar.temporal import Hertz, Time

AUDIO_CD_SAMPLING_RATE = 44100

@dataclass(frozen=True)
class Synthesizer:
    instrument: PluckedStringInstrument
    burst_generator: BurstGenerator = WhiteNoise()
    sampling_rate: int = AUDIO_CD_SAMPLING_RATE

    def strum_strings(
        self, chord: Chord, velocity: Velocity, vibration: Time | None = None
    ) -> np.ndarray:
        if vibration is None:
            vibration = self.instrument.vibration

        if velocity.direction is Direction.UP:
            stroke = self.instrument.upstroke
        else:
            stroke = self.instrument.downstroke

        sounds = tuple(
            self.vibrate(pitch.frequency, vibration, self.instrument.damping)
            for pitch in stroke(chord)
        )

        return self.overlay(sounds, velocity.delay)

    # ...

Your new .strum_strings() method expects a Chord and a Velocity instance at the minimum. You can optionally pass the vibration duration, but if you don’t, then the method falls back on the instrument’s default duration. Depending on the desired stroke direction, it synthesizes the pitches in ascending or descending string order. Finally, it overlays them with the required delay or arpeggiation.

Because .strum_strings() has become the only part of the public interface of your class, you can signal that the other two methods, vibrate() and overlay(), are intended for internal use only. A common convention in Python to denote non-public methods is to prefix their names with a single underscore (_):

# ...

@dataclass(frozen=True)
class Synthesizer:
    # ...

    def strum_strings(...) -> np.ndarray:
        # ...

        sounds = tuple(
            self._vibrate(pitch.frequency, vibration, self.instrument.damping)
            for pitch in stroke(chord)
        )

        return self._overlay(sounds, velocity.delay)

    def _vibrate(...) -> np.ndarray:
        # ...

    def _overlay(...) -> np.ndarray:
        # ...

It’s clear now that ._vibrate() and ._overlay() are implementation details that can change without notice, so you shouldn’t access them from an external scope.

Your synthesizer is almost complete, but it’s missing one crucial detail. If you were to synthesize a complete music piece, like the original Diablo soundtrack, then over ninety percent of the synthesis time would be spent on redundant computation. That’s because most songs consist of repeating patterns and motifs. It’s these repeated sequences of chords that create a recognizable rhythm.

To bring down the total synthesis time from minutes to seconds, you can incorporate caching of the intermediate results. Ideally, you’d want to decorate all methods in your Synthesizer class with the @cache decorator to compute them once for each unique list of arguments. However, caching requires that all method arguments are hashable.

While you diligently used immutable objects, which also happen to be hashable, NumPy arrays aren’t. Therefore, you can’t cache the results of your ._overlay() method, which takes a sequence of arrays as an argument. Instead, you can cache the other two methods that only rely on immutable objects:

from dataclasses import dataclass
from functools import cache
from itertools import cycle
from typing import Sequence

# ...

@dataclass(frozen=True)
class Synthesizer:
    # ...

    @cache
    def strum_strings(...) -> np.ndarray:
        # ...

    @cache
    def _vibrate(...) -> np.ndarray:
        # ...

    def _overlay(...) -> np.ndarray:
        # ...

With this little change, you essentially trade storage for speed. As long as your computer has enough memory, it’ll only take a fraction of the time it would have otherwise. Since the results are stored and retrieved, they won’t be recalculated each time they’re requested.

How about playing a few chords on some of your instruments? Below is a short code snippet that plays a downstroke strum on all open strings of three different plucked string instruments you defined earlier:

>>> from pedalboard.io import AudioFile

>>> from digitar.chord import Chord
>>> from digitar.instrument import PluckedStringInstrument, StringTuning
>>> from digitar.stroke import Direction, Velocity
>>> from digitar.synthesis import Synthesizer
>>> from digitar.temporal import Time

>>> instruments = {
...     "acoustic_guitar": PluckedStringInstrument(
...         tuning=StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4"),
...         vibration=Time(seconds=10),
...         damping=0.498,
...     ),
...     "banjo": PluckedStringInstrument(
...         tuning=StringTuning.from_notes("G4", "D3", "G3", "B3", "D4"),
...         vibration=Time(seconds=2.5),
...         damping=0.4965,
...     ),
...     "ukulele": PluckedStringInstrument(
...         tuning=StringTuning.from_notes("A4", "E4", "C4", "G4"),
...         vibration=Time(seconds=5.0),
...         damping=0.498,
...     ),
... }

>>> for name, instrument in instruments.items():
...     synthesizer = Synthesizer(instrument)
...     amplitudes = synthesizer.strum_strings(
...         Chord([0] * instrument.num_strings),
...         Velocity(Direction.DOWN, Time.from_milliseconds(40))
...     )
...     with AudioFile(f"{name}.mp3", "w", synthesizer.sampling_rate) as file:
...         file.write(amplitudes)

This code iterates through a dictionary of key-value pairs consisting of the instrument’s name and the corresponding PluckedStringInstrument instance. When you play the resulting audio files below, you’ll recognize the distinctive timbre of each instrument:

Alright. You have all the pieces together and are ready to play real music on your virtual guitar!

Allocate an Audio Track for Your Instrument

Music is made up of chords and notes arranged along a linear timeline, intentionally spaced to create rhythm and melody. A single song often contains more than one audio track corresponding to different instruments, such as lead guitar, bass guitar, and drums, as well as vocals.

You’ll represent an audio track with your first mutable class in this project to allow for incrementally adding and mixing sounds in chronological order. Define a new module named track with the following AudioTrack class in it:

import numpy as np

from digitar.temporal import Hertz, Time

class AudioTrack:
    def __init__(self, sampling_rate: Hertz) -> None:
        self.sampling_rate = int(sampling_rate)
        self.samples = np.array([], dtype=np.float64)

    def __len__(self) -> int:
        return self.samples.size

    @property
    def duration(self) -> Time:
        return Time(seconds=len(self) / self.sampling_rate)

    def add(self, samples: np.ndarray) -> None:
        self.samples = np.append(self.samples, samples)

An audio track contains a sequence of audio samples, or more precisely, the amplitude levels that you’ll encode as samples with a chosen data format. However, you’ll refer to them as samples to keep things simple.

To make a new instance of your AudioTrack class, you need to provide the desired sampling rate or frequency in hertz. It’ll let you calculate the track’s current duration in seconds, as well as add new samples at a specific time offset. As of now, you can only append samples at the very end of your existing track without the possibility of overlaying them earlier or inserting them later.

You’ll fix that now by implementing another method in your class:

# ...

class AudioTrack:
    # ...

    def add_at(self, instant: Time, samples: np.ndarray) -> None:
        samples_offset = round(instant.seconds * self.sampling_rate)
        if samples_offset == len(self):
            self.add(samples)
        elif samples_offset > len(self):
            self.add(np.zeros(samples_offset - len(self)))
            self.add(samples)
        else:
            end = samples_offset + len(samples)
            if end > len(self):
                self.add(np.zeros(end - len(self)))
            self.samples[samples_offset:end] += samples

This method, .add_at(), takes a time instant as an argument in addition to the sequence of samples to add. Based on the track’s sampling rate, it calculates the offset in terms of the number of audio samples. If the offset aligns with the current length of the audio track, then the method appends the samples by means of delegation to the .add() method.

Otherwise, the logic gets slightly more involved:

• Gap: If the offset is beyond the current length of the track, then the method fills the gap with zeros before appending the new samples as before.
• Full Overlap: If the offset is somewhere in the middle of the track and the new samples can fit within it, then the method overlays the new samples on top of the existing ones at the correct position.
• Partial Overlap: If the offset is somewhere in the middle of the track but the new samples reach beyond its current end, then the method blends the overlapping part and appends the remaining samples that extend beyond the current track length.

The new method lets you precisely place sounds within an audio track. But you still need to keep track of the progression of time on the timeline. You’ll create another custom data type to help you with that.

Track the Music Progression on a Timeline

Time can only move forward, so you’ll model the timeline as another mutable class with a special method for advancing the current instant. Open your temporal module now and add the following data class definition:

# ...

@dataclass
class Timeline:
    instant: Time = Time(seconds=0)

    def __rshift__(self, seconds: Numeric | Time) -> Self:
        self.instant += seconds
        return self

Unless you specify otherwise, a timeline starts at zero seconds by default. Thanks to the immutability of Time objects, you can use one as a default value for the instant attribute.

The .__rshift__() method provides the implementation of the bitwise right shift operator (>>) for your class. In this case, it’s a non-standard implementation, which has nothing to do with operations on bits. Instead, it advances the timeline by a given number of seconds or another Time object. The method updates the current Timeline instance in place and returns itself, allowing for method chaining or evaluating the shifted timeline right away.

Notice that shifting the timeline adds either a numeric value, such as a Decimal object, or a Time instance to another Time instance. This addition won’t work out of the box because Python doesn’t know how to add two objects of custom data types using the plus operator (+). Fortunately, you can tell it how to handle such an addition by implementing the .__add__() method in your Time class:

# ...

@dataclass(frozen=True)
class Time:
    # ...

    def __add__(self, seconds: Numeric | Self) -> Self:
        match seconds:
            case Time() as time:
                return Time(self.seconds + time.seconds)
            case int() | Decimal():
                return Time(self.seconds + seconds)
            case float():
                return Time(self.seconds + Decimal(str(seconds)))
            case Fraction():
                return Time(Fraction.from_decimal(self.seconds) + seconds)
            case _:
                raise TypeError(f"can't add '{type(seconds).__name__}'")

    def get_num_samples(self, sampling_rate: Hertz) -> int:
        return round(self.seconds * round(sampling_rate))

# ...

When you provide a Time object as an argument to .__add__(), then the method calculates the sum of the decimal seconds in both instances and returns a new Time instance with the resulting seconds. On the other hand, if the argument is one of the expected numeric types, then the method converts it appropriately first. In case of an unsupported type, the method raises an exception with an error message.

Review the following examples to understand how you can use the Timeline class:

>>> from digitar.temporal import Time, Timeline

>>> Timeline()
Timeline(instant=Time(seconds=Decimal('0')))

>>> Timeline(instant=Time.from_milliseconds(100))
Timeline(instant=Time(seconds=Decimal('0.1')))

>>> Timeline() >> 0.1 >> 0.3 >> 0.5
Timeline(instant=Time(seconds=Decimal('0.9')))

>>> from digitar.temporal import Time, Timeline
>>> timeline = Timeline()
>>> for offset in 0.1, 0.3, 0.5:
...     timeline >> offset
...
Timeline(instant=Time(seconds=Decimal('0.1')))
Timeline(instant=Time(seconds=Decimal('0.4')))
Timeline(instant=Time(seconds=Decimal('0.9')))

>>> timeline.instant.seconds
Decimal('0.9')

These examples showcase various ways of using the overridden bitwise operator to move through time. In particular, you can chain multiple time increments in one expression to advance the timeline cumulatively. A timeline is persistent, so any previous changes are retained in it, letting you query the current instant.

With an audio track and a timeline, you can finally compose your first melody. Are you ready to have some fun?

Repeat Chords in Spaced Time Intervals

For starters, you’ll play the chorus from Jason Mraz’s hit song “I’m Yours” on a virtual ukulele. The following example is based on an excellent explanation generously provided by Adrian from the Learn And Play channel on YouTube. If you’re interested in learning more about how to play this particular song, then check out a much more involved video tutorial on Adrian’s sister channel.

The chorus of the song consists of four chords in the following sequence with their corresponding fingering patterns for a ukulele:

1. C major: Press the third fret on the first string
2. G major: Press the second fret on the first string, the third fret on the second string, and the second fret on the third string
3. A minor: Press the second fret on the fourth string
4. F major: Press the first fret on the second string and the second fret on the fourth string

Additionally, each chord should be played according to the strumming pattern depicted below, repeated twice:

1. Downstroke (slow)
2. Downstroke (slow)
3. Upstroke (slow)
4. Upstroke (fast)
5. Downstroke (fast)
6. Upstroke (slow)

In other words, you begin by placing your fingers on the fretboard to form the desired chord, and then you keep stroking the strings in the prescribed pattern. When you reach the end of that pattern, you rinse and repeat by playing through it once more for the same chord. After you’ve strummed through the pattern twice for a particular chord, you move on to the next chord in the sequence.

The subsequent strokes in the pattern are spaced roughly at these time intervals in seconds:

While the specific chord offsets were estimated by ear, they’re good enough for the sake of this exercise. You’ll use them to spread the synthesized chords across an audio track with the help of a timeline.

Putting it together, you can create a Python script named play_chorus.py that replicates the strumming pattern of the song’s chorus. To keep things tidy, consider making a new subfolder in your project’s root folder, where you’ll store such scripts. For example, you can give it the name demo/:

from itertools import cycle
from typing import Iterator

from digitar.chord import Chord
from digitar.stroke import Velocity
from digitar.temporal import Time

def strumming_pattern() -> Iterator[tuple[float, Chord, Velocity]]:
    chords = (
        Chord.from_numbers(0, 0, 0, 3),
        Chord.from_numbers(0, 2, 3, 2),
        Chord.from_numbers(2, 0, 0, 0),
        Chord.from_numbers(2, 0, 1, 0),
    )

    fast = Time.from_milliseconds(10)
    slow = Time.from_milliseconds(25)

    strokes = [
        Velocity.down(slow),
        Velocity.down(slow),
        Velocity.up(slow),
        Velocity.up(fast),
        Velocity.down(fast),
        Velocity.up(slow),
    ]

    interval = cycle([0.65, 0.45, 0.75, 0.2, 0.4, 0.25])

    for chord in chords:
        for _ in range(2):  # Repeat each chord twice
            for stroke in strokes:
                yield next(interval), chord, stroke

The strumming_pattern() function above returns an iterator of triplets, consisting of the time interval in seconds, a Chord instance, and a Velocity object that describes a stroke. The interval is an offset of the next chord on the timeline relative to the current chord.

Each chord indicates the fret numbers to press on the respective strings. Remember that strings are counted from the right side, so the last element in the chord’s tuple represents the first string.

There are four types of strokes in total. Both upstroke and downstroke come in two flavors: slow and fast, which differ in the amount of delay between the consecutive plucks. You alternate between these strokes to simulate the expected rhythm.

Next, you can define a virtual ukulele and hook it up to the synthesizer:

from itertools import cycle
from typing import Iterator

from digitar.chord import Chord
from digitar.instrument import PluckedStringInstrument, StringTuning
from digitar.stroke import Velocity
from digitar.synthesis import Synthesizer
from digitar.temporal import Time

def main() -> None:
    ukulele = PluckedStringInstrument(
        tuning=StringTuning.from_notes("A4", "E4", "C4", "G4"),
        vibration=Time(seconds=5.0),
        damping=0.498,
    )
    synthesizer = Synthesizer(ukulele)

# ...

if __name__ == "__main__":
    main()

Following Python’s name-main idiom, you define the main() function as the entry point to your script, and you call it at the bottom of the file. Then, you reuse the PluckedStringInstrument definition that you saw in an earlier section, which specifies the standard tuning of a ukulele.

The next step is to synthesize the individual chords—depending on how you stroke your virtual strings—and add them to an audio track at the right moment:

from itertools import cycle
from typing import Iterator

from digitar.chord import Chord
from digitar.instrument import PluckedStringInstrument, StringTuning
from digitar.stroke import Velocity
from digitar.synthesis import Synthesizer
from digitar.temporal import Time, Timeline
from digitar.track import AudioTrack

def main() -> None:
    ukulele = PluckedStringInstrument(
        tuning=StringTuning.from_notes("A4", "E4", "C4", "G4"),
        vibration=Time(seconds=5.0),
        damping=0.498,
    )
    synthesizer = Synthesizer(ukulele)
    audio_track = AudioTrack(synthesizer.sampling_rate)
    timeline = Timeline()
    for interval, chord, stroke in strumming_pattern():
        audio_samples = synthesizer.strum_strings(chord, stroke)
        audio_track.add_at(timeline.instant, audio_samples)
        timeline >> interval

# ...

Based on the synthesizer’s sampling rate, you create an audio track and a timeline that starts at zero seconds. You then iterate over the strumming pattern, synthesize the next ukulele sound, and add it to the audio track at the current instant. Lastly, you advance the timeline using the provided offset.

You can now save the amplitudes retained in your audio track to a file, remembering to normalize them to avoid clipping and other distortion:

from itertools import cycle
from typing import Iterator

from pedalboard.io import AudioFile

from digitar.chord import Chord
from digitar.instrument import PluckedStringInstrument, StringTuning
from digitar.processing import normalize
from digitar.stroke import Velocity
from digitar.synthesis import Synthesizer
from digitar.temporal import Time, Timeline
from digitar.track import AudioTrack

def main() -> None:
    ukulele = PluckedStringInstrument(
        tuning=StringTuning.from_notes("A4", "E4", "C4", "G4"),
        vibration=Time(seconds=5.0),
        damping=0.498,
    )
    synthesizer = Synthesizer(ukulele)
    audio_track = AudioTrack(synthesizer.sampling_rate)
    timeline = Timeline()
    for interval, chord, stroke in strumming_pattern():
        audio_samples = synthesizer.strum_strings(chord, stroke)
        audio_track.add_at(timeline.instant, audio_samples)
        timeline >> interval

    with AudioFile("chorus.mp3", "w", audio_track.sampling_rate) as file:
        file.write(normalize(audio_track.samples))

# ...

When you run this script, you’ll end up with an audio file named chorus.mp3, which records the strumming pattern and chords of the song:

Give yourself a well-deserved pat on the back! You’ve just made a plucked string instrument synthesizer. It works decently well but requires you to manually schedule the individual notes on the timeline to match the rhythm. That can be error-prone and clunky. Plus, you can’t change the song’s tempo or the number of beats per minute.

Next up, you’ll take a more systematic approach to arranging the musical notes and chords on the timeline.

Divide the Timeline Into Measures of Beats

Music revolves around time, which is central to rhythm, tempo, and the duration of the individual notes within a composition. Throughout history, composers have found it convenient to divide the timeline into segments known as measures or bars, usually containing an equal number of beats.

You can think of the beat as the basic unit of time in a musical composition. It’s a steady pulse that determines the rhythm. The beat typically remains consistent throughout a song, and you can intuitively recognize it by tapping your feet or clapping your hands to it. Musicians sometimes deliberately count beats out loud or in their heads to maintain the timing of their performance.

Each measure has an associated time signature consisting of two numbers stacked vertically. The top number indicates how many beats are in the measure, and the bottom number denotes a fractional note value, which represents the length of one beat relative to the whole note. For instance, in a ⁴⁄₄ time signature (4 × ¼), there are four beats per measure, and the beat duration is equal to a quarter note or ¼-th of the whole note.

For historical reasons and the performer’s convenience, the note value in a time signature is almost always a power of two, allowing for a straightforward subdivision of the beats. When you want to play a note in between the main beats of your measure, as opposed to on the beat, you can increase the resolution by using smaller note values. However, they must follow a binary series:

In practice, notes shorter than one-sixteenth are rarely used. You may also combine a few of the standard note values to form even more complex dotted notes. For instance, ¼ + ⅛ + ¹⁄₁₆ gives you ⁷⁄₁₆, which can help you create intricate rhythms.

When you represent your notes using relative quantities instead of absolute ones, you can effortlessly control the tempo or pace of your entire composition. Knowing the mutual relationships between the individual notes lets you work out how long to play them.

Say you have a piece of music in common time. If you set the tempo to seventy-five beats per minute (BPM), then each beat, which happens to be a quarter note in this time signature, will last for 0.8 seconds. Four beats, making up a single measure, will last for 3.2 seconds. You can multiply that by the total number of measures in the composition to find its duration.

To accurately represent fractional note durations in seconds, you’ll implement yet another special method in your Time class:

# ...

@dataclass(frozen=True)
class Time:
    # ...

    def __mul__(self, seconds: Numeric) -> Self:
        match seconds:
            case int() | Decimal():
                return Time(self.seconds * seconds)
            case float():
                return Time(self.seconds * Decimal(str(seconds)))
            case Fraction():
                return Time(Fraction.from_decimal(self.seconds) * seconds)
            case _:
                raise TypeError(f"can't multiply by '{type(seconds).__name__}'")

    # ...

# ...

The .__mul__() method lets you overload the multiplication operator (*) in your class. In this case, multiplying a Time instance by a numeric value returns a new Time object with the updated decimal seconds.

@dataclass(frozen=True)
class Time:
    # ...

    def __radd__(self, seconds: Numeric | Self) -> Self:
        return self + seconds

    def __rmul__(self, seconds: Numeric) -> Self:
        return self * seconds

Thanks to the support for the Fraction data type in your multiplication method, you can elegantly express the duration of musical notes and measures:

>>> from fractions import Fraction
>>> from digitar.temporal import Time

>>> beats_per_minute = 75
>>> beats_per_measure = 4
>>> note_value = Fraction(1, 4)

>>> beat = Time(seconds=60 / beats_per_minute)
>>> measure = beat * beats_per_measure

>>> beat
Time(seconds=Decimal('0.8'))

>>> measure
Time(seconds=Decimal('3.2'))

>>> whole_note = beat * note_value.denominator
>>> half_note = whole_note * Fraction(1, 2)
>>> quarter_note = whole_note * Fraction(1, 4)
>>> three_sixteenth_note = whole_note * (Fraction(1, 8) + Fraction(1, 16))

>>> three_sixteenth_note
Time(seconds=Decimal('0.6'))

This code snippet demonstrates how you can precisely calculate the duration of various musical notes in terms of seconds. It starts by specifying the tempo (75 BPM) and the ⁴⁄₄ time signature. You use this information to get the duration of a single beat and one measure in seconds. Based on the beat’s length and the note value, you then derive the duration of the whole note and its fractions.

Your existing Timeline class only understands seconds when it comes to tracking time progression. In the next section, you’ll extend it to also support musical measures that you can quickly jump to.

Implement a Measure-Tracking Timeline

When you read musical notation, such as guitar tablature, you need to arrange the notes on a timeline using relative offsets within the current measure to ensure accurate timing and rhythm. You’ve seen how to determine the note’s duration, and you can place it on a timeline. However, you have no way of finding the measure boundaries and advancing to the next measure if the current one isn’t fully filled yet.

Go ahead and define another mutable data class that extends your Timeline base class with two additional fields, .measure and .last_measure_ended_at:

from dataclasses import dataclass, field

# ...

@dataclass
class MeasuredTimeline(Timeline):
    measure: Time = Time(seconds=0)
    last_measure_ended_at: Time = field(init=False, repr=False)

Once you inherit from another data class that has at least one field with a default value, you must declare default values in your subclass as well. That’s because non-default fields can’t follow default ones, even if they’re defined in the superclass. So, to satisfy the syntactical requirements, you specify zero seconds as the default value for the .measure field, even though you’ll typically provide your own value during object creation.

While the first attribute indicates the current measure’s duration, the second attribute keeps track of when the last measure ended. Because its value depends on the timeline’s .instant and .measure fields, you must initialize it manually in .__post_init__():

# ...

@dataclass
class MeasuredTimeline(Timeline):
    measure: Time = Time(seconds=0)
    last_measure_ended_at: Time = field(init=False, repr=False)

    def __post_init__(self) -> None:
        if self.measure.seconds > 0 and self.instant.seconds > 0:
            periods = self.instant.seconds // self.measure.seconds
            self.last_measure_ended_at = Time(periods * self.measure.seconds)
        else:
            self.last_measure_ended_at = Time(seconds=0)

If the measure size has been specified and the current position on the timeline is greater than zero seconds, then you calculate the number of complete measures that have passed and set .last_measure_ended_at accordingly. Otherwise, you leave it at the default value of zero seconds.

You can continue to use the bitwise right shift operator (>>) as before to advance the timeline’s .instant attribute. However, you also want to jump to the next measure at any time, even when you’re still in the middle of another measure. To do so, you can implement the .__next__() method in your class as follows:

 # ...

@dataclass
class MeasuredTimeline(Timeline):
    # ...

    def __next__(self) -> Self:
        if self.measure.seconds <= 0:
            raise ValueError("measure duration must be positive")
        self.last_measure_ended_at += self.measure
        self.instant = self.last_measure_ended_at
        return self

Before you try to update the other fields, you ensure that the current measure’s duration in seconds is positive. When it is, you add the duration to the .last_measure_ended_at attribute, marking the end of the current measure. Then, you set the timeline’s .instant attribute to this new value in order to move forward to the start of the next measure. Finally, you return your MeasuredTimeline object to allow for method and operator chaining.

After you create an instance of the class with a non-zero measure size, you can start jumping between the measures:

>>> from digitar.temporal import MeasuredTimeline, Time

>>> timeline = MeasuredTimeline(measure=Time(seconds=3.2))

>>> timeline.instant
Time(seconds=Decimal('0'))

>>> (timeline >> Time(0.6) >> Time(0.8)).instant
Time(seconds=Decimal('1.4'))

>>> next(timeline).instant
Time(seconds=Decimal('3.2'))

>>> timeline.measure = Time(seconds=2.0)

>>> next(timeline).instant
Time(seconds=Decimal('5.2'))

Unless you tell it otherwise, the MeasuredTimeline object starts at zero seconds, just like the regular timeline. You can use the bitwise right shift operator as usual. Additionally, by calling the built-in next() function, you can skip the remaining part of the current measure and move to the start of the next measure. When you decide to change the measure’s size, it gets reflected in subsequent calls to next().

Now that you’re acquainted with musical measures, beats, and fractional notes, you’re ready to synthesize a composition based on a real guitar tablature.

Learn How to Read Guitar Tablature

As previously mentioned, guitar tablature, often abbreviated as guitar tab, is a simplified form of musical notation geared toward beginner players and hobbyists who might feel less comfortable with traditional sheet music. At the same time, professional musicians don’t shy away from using guitar tabs due to their convenience for teaching and sharing ideas.

Because this notation is specifically designed for string instruments, a guitar tab contains horizontal lines representing the strings with numbers on top of them indicating which frets to press down. Depending on the type of instrument, the number of lines can vary, but there will be six lines for a typical guitar.

The ordering of guitar strings in a tab isn’t standardized, so always look for labels indicating the string numbers or letters corresponding to their tuning.

You can look up free guitar tabs online. As mentioned at the start of this tutorial, Songsterr is a community-driven website hosting over a million tabs. Chances are you’ll find the tabs for your favorite tunes over there. As part of this example, you’ll be re-creating the iconic soundtrack from the game Diablo.

Take a look at the game’s Tristram Theme by Matt Uelmen on Songsterr now. The screenshot below reveals its first four measures while annotating the most important elements of the guitar tab:

The tablature above begins with string labels corresponding to the guitar’s standard tuning, the ⁴⁄₄ time signature, and a seventy-five beats per minute tempo. Each measure is numbered and separated from its neighbors by a vertical line to help you orient yourself as you read through the music.

The bolded numbers that appear on the horizontal lines indicate the frets you should press on the corresponding strings to sound the desired chord. Finally, the symbols below each measure represent the fractional duration of notes and rests (pauses) relative to the whole note.

Based on this knowledge, you can interpret the provided tab and breathe life into it with the help of the guitar synthesizer that you’ve implemented. Initially, you’ll hard code the Diablo guitar tab in a Python script using a programmatic approach.

Play Diablo Tablature Programmatically

Create a new script called play_diablo.py in the demo/ folder with the following content:

from fractions import Fraction

from digitar.temporal import Time

BEATS_PER_MINUTE = 75
BEATS_PER_MEASURE = 4
NOTE_VALUE = Fraction(1, 4)

class MeasureTiming:
    BEAT = Time(seconds=60 / BEATS_PER_MINUTE)
    MEASURE = BEAT * BEATS_PER_MEASURE

class Note:
    WHOLE = MeasureTiming.BEAT * NOTE_VALUE.denominator
    SEVEN_SIXTEENTH = WHOLE * Fraction(7, 16)
    FIVE_SIXTEENTH = WHOLE * Fraction(5, 16)
    THREE_SIXTEENTH = WHOLE * Fraction(3, 16)
    ONE_EIGHTH = WHOLE * Fraction(1, 8)
    ONE_SIXTEENTH = WHOLE * Fraction(1, 16)
    ONE_THIRTY_SECOND = WHOLE * Fraction(1, 32)

class StrummingSpeed:
    SLOW = Time.from_milliseconds(40)
    FAST = Time.from_milliseconds(20)
    SUPER_FAST = Time.from_milliseconds(5)

The highlighted constants represent the only input parameters that you can change, while the remaining values are derived from those inputs. Here, you group logically related values under common namespaces by defining them as class attributes. The respective class names tell you their purpose.

Next, define your virtual guitar, hook it up to the synthesizer, and prepare the audio track along with the timeline that’s aware of the tab measures:

from fractions import Fraction

from pedalboard.io import AudioFile

from digitar.instrument import PluckedStringInstrument, StringTuning
from digitar.processing import normalize
from digitar.synthesis import Synthesizer
from digitar.temporal import MeasuredTimeline, Time
from digitar.track import AudioTrack

# ...

def main() -> None:
    acoustic_guitar = PluckedStringInstrument(
        tuning=StringTuning.from_notes("E2", "A2", "D3", "G3", "B3", "E4"),
        vibration=Time(seconds=10),
        damping=0.498,
    )
    synthesizer = Synthesizer(acoustic_guitar)
    audio_track = AudioTrack(synthesizer.sampling_rate)
    timeline = MeasuredTimeline(measure=MeasureTiming.MEASURE)
    save(audio_track, "diablo.mp3")

def save(audio_track: AudioTrack, filename: str) -> None:
    with AudioFile(filename, "w", audio_track.sampling_rate) as file:
        file.write(normalize(audio_track.samples))
    print(f"\nSaved file {filename!r}")

if __name__ == "__main__":
    main()

You reuse the acoustic guitar object from previous sections, which applies the standard tuning, and you define a helper function to save the resulting audio in a file.

What you’ll put on the timeline are synthesized sounds described by the current instant, the fret numbers to press, and the stroke velocity, which you can model as an immutable data class:

from dataclasses import dataclass
from fractions import Fraction

from pedalboard.io import AudioFile

from digitar.chord import Chord
from digitar.instrument import PluckedStringInstrument, StringTuning
from digitar.processing import normalize
from digitar.stroke import Velocity
from digitar.synthesis import Synthesizer
from digitar.temporal import MeasuredTimeline, Time
from digitar.track import AudioTrack

# ...

@dataclass(frozen=True)
class Stroke:
    instant: Time
    chord: Chord
    velocity: Velocity

# ...