Klang C++ 0.7.15
Language Reference (draft)
Loading...
Searching...
No Matches
klang::Sample

Language Guide / Samples and Wavetables

Sample

klang::Sample

A sample generator with variable-rate playback.

Assign a populated mono buffer to borrow its samples. Keep the sample storage alive while the player uses it. Playback starts at the first sample and interpolates between samples. By default, it plays once and outputs silence after the end. Set sample.mode = Looped to wrap at the buffer boundaries. You can change the mode during playback.

Example · Play a buffer once

Declare Sample sample; as a member. Here recorded is a buffer already populated with mono audio samples. Attach it during setup. Playback starts at normal speed.

sample = recorded;

Route the next sample to the output in process().

sample >> out;

Choose a playback mode

The default mode is OneShot. Set sample.mode or assign OneShot or Looped directly to change the mode at the current playhead.

sample.mode = Looped;
sample = OneShot;

When attaching a buffer, you can also supply metadata and a mode. The assignment rewinds playback. Omitted metadata or mode keep their current values. Here are three alternative setup forms.

sample = { recorded, Looped };
sample = { recorded, { 440, 44100 } };
sample = { recorded, { 440, 44100 }, OneShot };

Play by rate

Call set(rate) to set the speed multiplier. A rate of 1 plays at normal speed, 0.5 at half speed, and a negative rate plays backwards. To start a one-shot in reverse, use set(rate, time) to seek to a time within the recording. Zero holds the current position. If the recording’s sample rate is known, the player compensates for the host sample rate.

Set the recording metadata

Set info.frequency to the recording’s root frequency in Hz and info.samplerate to its recording rate in samples per second. Both default to zero, which represents an unknown value. Here the recording is an A4 tone sampled at 44.1 kHz.

sample.info = { 440, 44100 };

Use a MIDI note to specify the root pitch when that is how the recording was labelled.

sample.info = { Pitch(60) -> Frequency, 48000 };

Play by target frequency

Use set(Frequency(f)) or set(Hz(f)) to set the target frequency. Hz is an alias for Frequency. With a known root frequency, the speed multiplier is the target divided by the root. A known recording sample rate then converts that multiplier to the appropriate step for the host. Without a root, a known recording rate lets the target specify the number of source samples read per second. With both metadata values zero, the frequency call leaves the current speed in place.

This uses the A4 recording above to play an octave higher. Use the same typed argument in an inline call to set the speed and read a sample in one expression.

sample.set(Hz(880));

Sample-based signal generator with variable-rate playback. More...

#include <klang.h>

+ Inheritance diagram for klang::Sample:

Classes

struct  Binding
 Buffer assignment with optional recording metadata and playback mode. More...
 
struct  Info
 Optional root pitch in Hz and recording sample rate in samples per second. More...
 

Public Types

enum  Mode { OneShot , Looped }
 Select one-shot or looping playback. More...
 

Public Member Functions

 Sample ()
 
signal & operator[] (int index)
 
Sample & operator= (const klang::buffer &source)
 Borrow the sample storage and return to the start of the buffer.
 
Sample & operator= (Mode mode)
 Change the mode without moving the playback position.
 
Sample & operator= (const Binding &binding)
 
void set (param rate) override
 Set the playback speed, with one representing the original rate.
 
template<typename TYPE , std::enable_if_t< std::is_same_v< TYPE, Frequency >, int > = 0>
void set (TYPE frequency)
 Set playback speed from a target frequency and the available metadata.
 
Sample & operator() (Frequency frequency)
 
void set (param rate, param time) override
 Set playback speed and seek to a time in seconds.
 
void set (relative time) override
 Set a read offset in seconds.
 
void set (param rate, relative time) override
 
void reset ()
 Rewind the playback position.
 
void process () override
 
Output< signal > & operator() (params &&... p)
 
 operator const signal & () override
 
 operator const signal & () const override
 
virtual const signal & output () const
 
TYPE & operator>> (TYPE &destination)
 
signal operator+ (TYPE &other)
 
signal operator* (TYPE &other)
 
signal operator- (TYPE &other)
 
signal operator/ (TYPE &other)
 

Public Attributes

struct klang::Sample::Info info
 
Mode mode = OneShot
 
signal out
 

Protected Attributes

buffer buffer
 
int size = 0
 

Detailed Description

Definition at line 4896 of file klang.h.


Class Documentation

◆ klang::Sample::Info

struct klang::Sample::Info

Definition at line 4907 of file klang.h.

Class Members
Frequency frequency = 0
SampleRate samplerate = 0

Member Enumeration Documentation

◆ Mode

Values
OneShot 
Looped 

Definition at line 4913 of file klang.h.

4913{ OneShot, Looped };

Constructor & Destructor Documentation

◆ Sample()

klang::Sample::Sample ( )
inline

Definition at line 4930 of file klang.h.

4930: buffer(nullptr, 0) {}
buffer buffer
Definition klang.h:4900

Member Function Documentation

◆ operator const signal &() [1/2]

klang::Generic::Generator< signal >::operator const signal & ( ) const
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3057 of file klang.h.

3057{ return out; } // return last output

◆ operator const signal &() [2/2]

klang::Generic::Generator< signal >::operator const signal & ( )
inlineoverridevirtualinherited

Reimplemented from klang::Generic::Output< signal >.

Definition at line 3056 of file klang.h.

3056{ this->process(); return out; } // return processed output

◆ operator()() [1/2]

Output< signal > & klang::Generic::Generator< signal >::operator() ( params &&... p)
inlineinherited

Definition at line 3050 of file klang.h.

3050 {
3051 set(std::forward<params>(p)...); return *this;
3052 }

◆ operator()() [2/2]

Sample & klang::Sample::operator() ( Frequency frequency)
inline

Definition at line 4971 of file klang.h.

4971 {
4972 set(frequency);
4973 return *this;
4974 }
void set(param rate) override
Set the playback speed, with one representing the original rate.
Definition klang.h:4957

◆ operator*()

signal klang::Generic::Output< signal >::operator* ( TYPE & other)
inlineinherited

Definition at line 2977 of file klang.h.

2977{ this->process(); return out * SIGNAL(other); }

◆ operator+()

signal klang::Generic::Output< signal >::operator+ ( TYPE & other)
inlineinherited

Definition at line 2976 of file klang.h.

2976{ this->process(); return out + SIGNAL(other); }

◆ operator-()

signal klang::Generic::Output< signal >::operator- ( TYPE & other)
inlineinherited

Definition at line 2978 of file klang.h.

2978{ this->process(); return out - SIGNAL(other); }

◆ operator/()

signal klang::Generic::Output< signal >::operator/ ( TYPE & other)
inlineinherited

Definition at line 2979 of file klang.h.

2979{ this->process(); return out / SIGNAL(other); }

◆ operator=() [1/3]

Sample & klang::Sample::operator= ( const Binding & binding)
inline

Definition at line 4950 of file klang.h.

4950 {
4951 if (binding.info) info = *binding.info;
4952 if (binding.mode) mode = *binding.mode;
4953 return *this = binding.source;
4954 }
struct klang::Sample::Info info

◆ operator=() [2/3]

Sample & klang::Sample::operator= ( const klang::buffer & source)
inline

Definition at line 4937 of file klang.h.

4937 {
4938 size = source.size;
4939 if (size > 0) buffer.attach(source, size);
4940 reset();
4941 return *this;
4942 }
void reset()
Rewind the playback position.
Definition klang.h:4993
const int size
Definition klang.h:2631
void attach(const buffer &buffer, int size=0)
Definition klang.h:2659

◆ operator=() [3/3]

Sample & klang::Sample::operator= ( Mode mode)
inline

Definition at line 4945 of file klang.h.

4945 {
4946 this->mode = mode;
4947 return *this;
4948 }

◆ operator>>()

TYPE & klang::Generic::Output< signal >::operator>> ( TYPE & destination)
inlineinherited

Definition at line 2969 of file klang.h.

2969{ this->process(); return destination = out; }

◆ operator[]()

signal & klang::Sample::operator[] ( int index)
inline

Definition at line 4932 of file klang.h.

4932 {
4933 return buffer[index];
4934 }

◆ output()

virtual const signal & klang::Generic::Output< signal >::output ( ) const
inlinevirtualinherited

Definition at line 2964 of file klang.h.

2964{ return out; }

◆ process()

void klang::Sample::process ( )
inlineoverridevirtual

Implements klang::Generic::Output< signal >.

Definition at line 4995 of file klang.h.

4995 {
4996 const bool looped = mode == Looped;
4997 double read = position + offset;
4998 if (size == 0 || (!looped && (read < 0 || read >= size))) {
4999 out = 0;
5000 return;
5001 }
5002 if (looped) read = wrap(read);
5003 const int index = int(read);
5004 const int next = index + 1 < size ? index + 1 : (looped ? 0 : index);
5005 const double fraction = read - index;
5006 out = buffer[index] * (1 - fraction) + buffer[next] * fraction;
5007 const float host = fs.f;
5008 const float recorded = info.samplerate.f;
5009 const double step = positive(recorded) && positive(host) ? rate * recorded / host : rate;
5010 position += step;
5011 if (looped) position = wrap(position);
5012 }
SampleRate samplerate
Definition klang.h:4909
klang::dB fs
float f
sample rate (float)
Definition klang.h:1744

◆ reset()

void klang::Sample::reset ( )
inline

Definition at line 4993 of file klang.h.

4993{ position = 0; }

◆ set() [1/5]

void klang::Sample::set ( param rate)
inlineoverride

Definition at line 4957 of file klang.h.

4957 {
4958 if (finite(rate.value)) this->rate = rate.value;
4959 }

◆ set() [2/5]

void klang::Sample::set ( param rate,
param time )
inlineoverride

Definition at line 4977 of file klang.h.

4977 {
4978 set(rate);
4979 if (finite(time.value)) position = double(time.value) * sourceRate();
4980 }

◆ set() [3/5]

void klang::Sample::set ( param rate,
relative time )
inlineoverride

Definition at line 4987 of file klang.h.

4987 {
4988 set(rate);
4989 set(time);
4990 }

◆ set() [4/5]

void klang::Sample::set ( relative time)
inlineoverride

Definition at line 4983 of file klang.h.

4983 {
4984 if (finite(time.value)) offset = double(time.value) * sourceRate();
4985 }

◆ set() [5/5]

template<typename TYPE , std::enable_if_t< std::is_same_v< TYPE, Frequency >, int > = 0>
void klang::Sample::set ( TYPE frequency)
inline

Definition at line 4963 of file klang.h.

4963 {
4964 const float root = info.frequency.value;
4965 const float recorded = info.samplerate.f;
4966 const float reference = positive(root) ? root : positive(recorded) ? recorded : 0;
4967 if (reference > 0 && finite(frequency.value))
4968 rate = double(frequency.value) / reference;
4969 }
Frequency frequency
Definition klang.h:4908
float value
Definition klang.h:1124

Member Data Documentation

◆ buffer

buffer klang::Sample::buffer
protected

Definition at line 4900 of file klang.h.

◆ info

struct klang::Sample::Info klang::Sample::info

◆ mode

Mode klang::Sample::mode = OneShot

Definition at line 4914 of file klang.h.

◆ out

Definition at line 2961 of file klang.h.

2961{ 0.f };

◆ size

int klang::Sample::size = 0
protected

Definition at line 4901 of file klang.h.