sc3.synth.buffer module

Client-side representation of server’s buffers.

Buffers can allocate and initialize memory in many different ways. The default __init__ constructor allocates empty buffers initialized with zeros. To create just client-side buffer objects set alloc to False.

Other convenience constructors to allocate a initialize buffers are:

  • new_consecutive

  • new_read

  • new_read_no_update

  • new_read_channel

  • new_cue

  • new_load_list

  • new_send_list

Both memory allocation in the server and to retrieve buffer’s information are asynchornous operations.

For the first case, server’s commands provide completion messages which are OSC messages that are excecuted in the server as soon as the memory is available. Some constructors initialize data (e.g. buffer number) before sending any message, to send a completion message with that information wrap it into a function that returns the updated message, the function will be evaluated passing the buffer object with that data before sending.

For the second case, the client provides action functions (client-side asynchornous callbacks) wich are called after the buffer’s information is retrieved.

Example

# Completion message
b1 = Buffer(completion_msg=lambda buf: ['/do_something', buf.bufnum])

# Action function
b2 = Buffer.new_send_list(
    [1, 2, 3], action=lambda buf: print(buf.frames))

Note: Depending on allocation method the actual values of the properties need to be obtained from the server. This class does that automatically for all instances.

exception BufferException

Bases: Exception

exception BufferAlreadyFreed(method=None)

Bases: sc3.synth.buffer.BufferException

class Buffer(frames=None, channels=1, server=None, bufnum=None, completion_msg=None, *, alloc=True, cache=True)

Bases: sc3.synth._graphparam.UGenParameter, sc3.synth._graphparam.NodeParameter

Create a new empty buffer. If alloc is True (default) creating a buffer object will immediately send the message to alloc the memory in the server. Buffers are filled with zeros by default.

Parameters

  • frames (int) – Number of frames.

  • channels (int) – Number of channels.

  • server (Server) – Target server on which memory will be allocated.

  • bufnum (int) – Number (id) of the buffer. By default, buffer numbers are managed by the library (recomended).

  • completion_msg (list | function) – An OSC message or a function that returns one. If alloc is False this parameter is ignored. The function will evaluated with the buffer object as argument.

  • alloc (bool) – If True (default) send the message to alloc the buffer in the server.

  • cache (bool) – If True (default) automatically update instance variables.

property frames

Number of frames.

property channels

Number of channels.

property server

Target server.

property bufnum

Buffer’s number in the server.

property path

Path for buffers allocated by read.

property start_frame

Start frame of buffers allocated by read.

property sample_rate

Sample rate of the buffer, may not be the same as the server.

property duration

Duration of the buffer in seconds.

classmethod new_consecutive(buffers=1, frames=1024, channels=1, server=None, bufnum=None, completion_msg=None)

Allocate a range of consecutively-numbered buffers, for use with ugens like VOsc and VOsc3 that require a contiguous block of buffers, and return an array of corresponding Buffer objects.

Parameters

  • buffers (int) – The number of consecutively indexed buffers to allocate.

  • frames (int) – The number of frames to allocate in each buffer.

  • channels (int) – Number of channels for each buffer.

  • server (Server) – The server on which to allocate the buffers. The default is the default server.

  • bufnum (int) – Number (id) of the buffer. By default, buffer numbers are managed by the library (recomended).

  • completion_msg (list | function) – A valid OSC message or a function which will return one. A function will be passed each Buffer and its index in the array as arguments when evaluated.

  • Note (The array of buffers must be treated as a group. Freeing them) –

  • or reusing them can result in allocation errors. (individually) –

classmethod new_read(path, start_frame=0, frames=- 1, server=None, bufnum=None, action=None)

Allocate a buffer and immediately read a soundfile into it for use with ugens like PlayBuf.

Parameters

  • path (str) – Path of the sound file to read.

  • start_frame (int) – The first frame of the sound file to read. The default is 0, which is the beginning of the file.

  • frames (int) – The number of frames to read. The default is -1, which will read the whole file.

  • server (Server) – The server on which to allocate the buffer.

  • bufnum (int) – Number (id) of the buffer. By default, buffer numbers are managed by the library (recomended).

  • action (function) – A function to be evaluated once the file has been read and this buffer’s instance variables have been updated. The function will be passed this Buffer as an argument.

classmethod new_read_channel(path, start_frame=0, frames=- 1, channels=None, server=None, bufnum=None, action=None)

As new_read but takes a list of channel indices to read.

Parameters

  • path (str) – Path of the sound file to read.

  • start_frame (int) – The first frame of the sound file to read. The default is 0, which is the beginning of the file.

  • frames (int) – The number of frames to read. The default is -1, which will read the whole file.

  • channels (list) – A list of channels to be read from the soundfile. Indices start from zero. These will be read in the order provided.

  • server (Server) – The server on which to allocate the buffer.

  • bufnum (int) – Number (id) of the buffer. By default, buffer numbers are managed by the library (recomended).

  • action (function) – A function to be evaluated once the file has been read and this buffer’s instance variables have been updated. The function will be passed this Buffer as an argument.

classmethod new_cue(path, start_frame=0, buffer_size=32768, channels=1, server=None, bufnum=None, completion_msg=None)

Allocate a buffer and preload a soundfile for streaming in using DiskIn.

Parameters

  • path (str) – Path of the sound file to read.

  • start_frame (int) – The frame to start reading.

  • buffer_size (int) – Size of the buffer. It must be a multiple of (2 * the server’s block size), 32768 is the default and is suitable for most cases.

  • channels (int) – The number of channels in the sound file.

  • server (Server) – The server on which to allocate the buffer.

  • bufnum (int) – Number (id) of the buffer. By default, buffer numbers are managed by the library (recomended).

  • completion_msg (list | function) – An OSC message or a function that returns one. The function will evaluated with the initialized buffer object as argument.

classmethod new_load_list(lst, channels=1, server=None, action=None)

Allocate a buffer and load a large collection in a local server.

This is accomplished through writing the collection to a file and asking the server to read it. The sample rate of the buffer will be the sample rate of the server on which it is created.

Parameters

  • lst (list) – A list of samples. Multichannel data must be interleaved.

  • channels (int) – Number of data channels.

  • server (Server) – The server on which to allocate the buffer.

  • action (function) – A function to be evaluated once the file has been read and this buffer’s instance variables have been updated. The function will be passed this Buffer as an argument.

classmethod new_send_list(lst, channels=1, server=None, wait=- 1, action=None)

Allocate a buffer and stream a large collection into the buffer using multiple setn messages.

Parameters

  • lst (list) – A list of samples. Multichannel data must be interleaved.

  • channels (int) – Number of data channels.

  • server (Server) – The server on which to allocate the buffer.

  • wait (float | int) – An optional wait time between sending setn messages. In a high traffic situation it may be safer to set this to something above zero. A value <= to zero means no wait time.

  • action (function) – A function to be evaluated once the file has been read and this buffer’s instance variables have been updated. The function will be passed this Buffer as an argument.

alloc(completion_msg=None)

Allocate the necessary memory on the server for buffer objects previously created with alloc=False.

alloc_read(path, start_frame=0, frames=- 1, completion_msg=None)

Read a sound file on the server for buffer objects previously created with alloc=False.

alloc_read_channel(path, start_frame=0, frames=- 1, channels=None, completion_msg=None)

Read a sound file on the server for buffer objects previously created with alloc=False.

read(path, file_start_frame=0, frames=- 1, buf_start_frame=0, leave_open=False, action=None)

Read a soundfile into an already allocated buffer.

Parameters

  • path (str) – Path of the sound file to read.

  • file_start_frame (int) – The first frame of the sound file to read. The default is 0, which is the beginning of the file.

  • frames (int) – The number of frames to read. The default is -1, which will read the whole file.

  • buf_start_frame (int) – The index of the frame in the buffer at which to start reading. The default is 0, which is the beginning of the buffer.

  • leave_open (bool) – A boolean indicating whether or not the buffer should be left open. For use with DiskIn you will want this to be True, as the buffer will be used for streaming the soundfile in from disk. See cue method for memory requirements.

  • action (function) – A function to be evaluated once the file has been read and this buffer’s instance variables have been updated. The function will be passed this Buffer as an argument.

read_channel(path, file_start_frame=0, frames=- 1, buf_start_frame=0, leave_open=False, channels=None, action=None)

As read but allows to specify which channels to read in a list.

cue(path, start_frame=0, completion_msg=None)

Cue a sound file into the buffer for use with DiskIn.

The buffer must have been allocated with a multiple of (2 * the server’s block size) frames. A common size is 32768 frames.

Parameters

  • path (str) – Path of the sound file to read.

  • start_frame (int) – The first frame of the soundfile to read. The default is 0, which is the beginning of the file.

  • completion_msg (list | function) – An OSC message or a function that returns one. The function will evaluated with the initialized buffer object as argument.

write(path=None, header_format='aiff', sample_format='int24', frames=- 1, start_frame=0, leave_open=False, completion_msg=None)

Write the contents of the buffer to a file.

Parameters

  • path (str) – path of the soundfile to be written. If no path is given, it writes into the default recording directory with a generic name.

  • header_format (str) –

    …

  • sample_format (str) –

    …

  • frames (int) – The number of frames to write. The default is -1, which will write the whole buffer.

  • start_frame (int) – The index of the frame in the buffer from which to start writing.

  • leave_open (bool) – A boolean indicating whether or not the buffer should be left open. For use with DiskOut set it to True, default is False.

  • completion_msg (list | function) – An OSC message or a function that returns one. The function will evaluated with the initialized buffer object as argument.

close(completion_msg=None)

Close the associated sound file after using the buffer with a DiskOut or DiskIn (leave_open=True).

free(completion_msg=None)

Release the buffer’s memory on the server and return the buffer ID back to the server’s buffer number allocator for future reuse.

Parameters

completion_msg (list | function) – An OSC message or a function that returns one. The function will evaluated with the initialized buffer object as argument.

classmethod free_all(server=None)

Free all the buffers of the given server.

zero(completion_msg=None)

Sets all values in this buffer to 0.0.

Parameters

completion_msg (list | function) – An OSC message or a function that returns one. The function will evaluated with the initialized buffer object as argument.

fill(start, frames, values)

Starting at the index start, set the next number of frames to the list of values.

query(action=None)

Sends a b_query message to the server, asking for a description of this buffer. The results are posted to the post window. Does not update instance vars.

Parameters

action (function) – A function to be evaluated as response to the query replacing the default beahviour.

update_info(action=None)

Sends a ‘/b_query’ message to the server asking for a description of this buffer. Upon reply this buffer’s instance variables are automatically updated.

Parameters

action (function) – A function to be evaluated once instance variables have been updated. The function will evaluated with the buffer object as argument.

set(index, value, *more_pairs)
setn(*args)
load_list(lst, start_frame=0, action=None)
send_list(lst, start_frame=0, wait=- 1, action=None)
get(index, action)
getn(index, count, action)
load_to_list(action, index=0, count=- 1)
get_to_list(action, index=0, count=None, wait=0.01, timeout=3)
gen(cmd, args=(), normalize=True, as_wavetable=True, clear_first=True, action=None)
normalize(new_max=1, as_wavetable=False, action=None)
sine1(amps, normalize=True, as_wavetable=True, clear_first=True, action=None)
sine2(freqs, amps, normalize=True, as_wavetable=True, clear_first=True, action=None)
sine3(freqs, amps, phases, normalize=True, as_wavetable=True, clear_first=True, action=None)
cheby(amps, normalize=True, as_wavetable=True, clear_first=True, action=None)
copy_data(dst_buffer, dst_start=0, start=0, num_samples=- 1, action=None)
prepare_partconv(buf, fftsize)
static calc_partconv_bufsize(fftsize, irbuffer)