ptttl_sample_generator.h File Reference

Converts the output of ptttl_parse_next() into a stream of signed 16-bit audio samples suitable for a WAV file. Samples can be obtained one at a time, at your leisure. More...

#include <stdint.h>
#include "ptttl_parser.h"

Go to the source code of this file.

Classes
struct	ptttl_waveform_t
struct	ptttl_note_stream_t
struct	ptttl_sample_generator_config_t
struct	ptttl_sample_generator_t

Macros
#define	PTTTL_SAMPLE_GENERATOR_NUM_HARMONICS   16
#define	PTTTL_SAMPLE_GENERATOR_CONFIG_DEFAULT

Typedefs
typedef float(*	ptttl_waveform_generator_t) (float x, float p, unsigned int s, void *wgendata)
typedef void(*	ptttl_waveform_note_setup_t) (uint32_t channel_idx, uint8_t note_number, unsigned int sample_rate, void *wgendata)

Enumerations
enum	ptttl_waveform_type_e {   WAVEFORM_TYPE_SINE = 0 , WAVEFORM_TYPE_TRIANGLE , WAVEFORM_TYPE_SAWTOOTH , WAVEFORM_TYPE_SQUARE ,   WAVEFORM_TYPE_NOKIA , WAVEFORM_TYPE_COUNT }

Functions
int	ptttl_sample_generator_create (ptttl_parser_t *parser, ptttl_sample_generator_t *generator, ptttl_sample_generator_config_t *config)
int	ptttl_sample_generator_set_waveform (ptttl_sample_generator_t *generator, uint32_t channel, ptttl_waveform_type_e type)
int	ptttl_sample_generator_set_custom_waveform (ptttl_sample_generator_t *generator, uint32_t channel, const ptttl_waveform_t *waveform)
int	ptttl_sample_generator_generate (ptttl_sample_generator_t *generator, uint32_t *num_samples, int16_t *samples)

Detailed Description

Converts the output of ptttl_parse_next() into a stream of signed 16-bit audio samples suitable for a WAV file. Samples can be obtained one at a time, at your leisure.

Requires ptttl_parser.c

Requires stdint.h and memset() from string.h

See https://github.com/eriknyquist/ptttl for more details about PTTTL.

Author

Erik Nyquist

Macro Definition Documentation

PTTTL_SAMPLE_GENERATOR_CONFIG_DEFAULT

#define PTTTL_SAMPLE_GENERATOR_CONFIG_DEFAULT

Value:

                                               {.sample_rate=44100u, .attack_samples=100u, \
                                               .decay_samples=500u, .amplitude=0.8f}

ptttl_sample_generator_config_t object initialization with sane defaults

PTTTL_SAMPLE_GENERATOR_NUM_HARMONICS

#define PTTTL_SAMPLE_GENERATOR_NUM_HARMONICS   16

Number of harmonics to use when generating the square, sawtooth & triangle waveforms. Higher numbers generate higher quality waves, at the cost of increased sample generation time.

Typedef Documentation

ptttl_waveform_generator_t

typedef float(* ptttl_waveform_generator_t) (float x, float p, unsigned int s, void *wgendata)

Callback function for a waveform generator

Parameters

x	Phase; current position on the waveform, in turns (0.0 through 1.0)
p	Wave frequency in Hz
s	Sampling rate in Hz
wgendata	Pointer to waveform-specific data set up by ptttl_waveform_note_setup_t, may be NULL if no setup function is provided

Returns

Value for the given position, in the range -1.0 through 1.0

ptttl_waveform_note_setup_t

typedef void(* ptttl_waveform_note_setup_t) (uint32_t channel_idx, uint8_t note_number, unsigned int sample_rate, void *wgendata)

Optional per-note setup callback for a waveform generator.

Called once each time a new note starts. The implementation should write any note-specific data it needs (e.g. precomputed harmonic coefficients) into the wgendata buffer pointed to by the wgendata parameter, which is backed by ptttl_note_stream_t.wgendata_storage. The same pointer is passed as wgendata to the ptttl_waveform_generator_t on every subsequent sample for this note.

May be NULL if the waveform generator requires no per-note setup.

Parameters

channel_idx	Channel number the note belongs to. Channel numbers are in the same order that the channel occurs in the PTTTL/RTTTL source text, starting from 0.
note_number	Piano key number of the new note (1-88), or 0 for a rest
sample_rate	Sample rate in Hz
wgendata	Pointer to ptttl_note_stream_t.wgendata_storage; write note-specific data here

Enumeration Type Documentation

ptttl_waveform_type_e

enum ptttl_waveform_type_e

Enumerates all available built-in waveform types

Enumerator
WAVEFORM_TYPE_SINE	Generates a sine wave.
WAVEFORM_TYPE_TRIANGLE	Generates a triangle wave.
WAVEFORM_TYPE_SAWTOOTH	Generates a sawtooth wave.
WAVEFORM_TYPE_SQUARE	Generates a square wave.
WAVEFORM_TYPE_NOKIA	Mimics the sound of a Nokia 3310 phone.

Function Documentation

ptttl_sample_generator_create()

int ptttl_sample_generator_create	(	ptttl_parser_t *	parser,
		ptttl_sample_generator_t *	generator,
		ptttl_sample_generator_config_t *	config
	)

Initialize a sample generator instance for a specific PTTTL/RTTTL source text

Parameters

parser	Pointer to initialized PTTTL parser object
generator	Pointer to generator instance to initialize
config	Pointer to sample generator configuration data

Returns

0 if successful, -1 if an error occurred. Call ptttl_parser_error for an error description if -1 is returned.

ptttl_sample_generator_generate()

int ptttl_sample_generator_generate	(	ptttl_sample_generator_t *	generator,
		uint32_t *	num_samples,
		int16_t *	samples
	)

Generate the next audio sample(s) for an initialized generator object

Parameters

generator	Pointer to initialized generator object
num_samples	Pointer to number of samples to generate. If successful, then this pointer is re-used to write out the actual number of samples generated.
samples	Pointer to location to store sample values. The caller is expected to provide at least (sizeof(int16_t) * num_samples) bytes of storage for the generated samples.

Returns

0 if successful, 1 if all samples have been generated, and -1 if an error occurred. Call ptttl_parser_error for an error description if -1 is returned.

ptttl_sample_generator_set_custom_waveform()

int ptttl_sample_generator_set_custom_waveform	(	ptttl_sample_generator_t *	generator,
		uint32_t	channel,
		const ptttl_waveform_t *	waveform
	)

Set a fully custom waveform for a specific channel, including an optional per-note setup callback. The waveform struct pairs a generator function with an optional note_setup callback for precomputing per-note data.

Parameters

generator	Pointer to initialized generator object
channel	Channel index (0-based)
waveform	Pointer to waveform definition struct

Returns

0 if successful, -1 if an error occurred.

ptttl_sample_generator_set_waveform()

int ptttl_sample_generator_set_waveform	(	ptttl_sample_generator_t *	generator,
		uint32_t	channel,
		ptttl_waveform_type_e	type
	)

Set the built-in waveform type for a specific channel of the sample generator

Parameters

generator	Pointer to initialized generator object
channel	Channel index to set the waveform type for. Channel index is 0-based, and channels are indexed in the order in which they appear in the PTTTL source text. For example, channel 0 is the first channel that appears in the source text, channel 1 is the second channel, and so on.
type	Built-in waveform type to generate for the specified channel.

Returns

0 if successful, -1 if an error occurred. Call ptttl_parser_error for an error description if -1 is returned.