:mod:`sc3nb.sc_objects.buffer` ============================== .. py:module:: sc3nb.sc_objects.buffer .. autoapi-nested-parse:: Module for using SuperCollider Buffers in Python .. !! processed by numpydoc !! Module Contents --------------- Class List ~~~~~~~~~~ .. autoapisummary:: :nosignatures: sc3nb.sc_objects.buffer.BufferReply sc3nb.sc_objects.buffer.BufferCommand sc3nb.sc_objects.buffer.BufferAllocationMode sc3nb.sc_objects.buffer.BufferInfo sc3nb.sc_objects.buffer.Buffer Content ~~~~~~~ .. class:: BufferReply **Bases:** :class:`str`, :class:`enum.Enum` Buffer Command Replies Initialize self. See help(type(self)) for accurate signature. .. !! processed by numpydoc !! .. py:attribute:: INFO :value: '/b_info' .. class:: BufferCommand **Bases:** :class:`str`, :class:`enum.Enum` Buffer OSC Commands for Buffers Initialize self. See help(type(self)) for accurate signature. .. !! processed by numpydoc !! .. py:attribute:: ALLOC :value: '/b_alloc' .. py:attribute:: ALLOC_READ :value: '/b_allocRead' .. py:attribute:: ALLOC_READ_CHANNEL :value: '/b_allocReadChannel' .. py:attribute:: READ :value: '/b_read' .. py:attribute:: READ_CHANNEL :value: '/b_readChannel' .. py:attribute:: WRITE :value: '/b_write' .. py:attribute:: FREE :value: '/b_free' .. py:attribute:: ZERO :value: '/b_zero' .. py:attribute:: SET :value: '/b_set' .. py:attribute:: SETN :value: '/b_setn' .. py:attribute:: FILL :value: '/b_fill' .. py:attribute:: GEN :value: '/b_gen' .. py:attribute:: CLOSE :value: '/b_close' .. py:attribute:: QUERY :value: '/b_query' .. py:attribute:: GET :value: '/b_get' .. py:attribute:: GETN :value: '/b_getn' .. class:: BufferAllocationMode **Bases:** :class:`str`, :class:`enum.Enum` Buffer Allocation Modes Initialize self. See help(type(self)) for accurate signature. .. !! processed by numpydoc !! .. py:attribute:: FILE :value: 'file' .. py:attribute:: ALLOC :value: 'alloc' .. py:attribute:: DATA :value: 'data' .. py:attribute:: EXISTING :value: 'existing' .. py:attribute:: COPY :value: 'copy' .. py:attribute:: NONE :value: 'none' .. class:: BufferInfo **Bases:** :class:`NamedTuple` Information about the Buffer .. !! processed by numpydoc !! .. py:attribute:: bufnum :type: int .. py:attribute:: num_frames :type: int .. py:attribute:: num_channels :type: int .. py:attribute:: sample_rate :type: float .. class:: Buffer(bufnum: Optional[int] = None, server: Optional[sc3nb.sc_objects.server.SCServer] = None) A Buffer object represents a SuperCollider3 Buffer on scsynth and provides access to low-level buffer commands of scsynth via methods of the Buffer objects. The constructor merely initializes a buffer: * it selects a buffer number using the server's buffer allocator * it initializes attribute variables :Parameters: **bufnum** : int, optional buffer number to be used on scsynth. Defaults to None, can be set to enforce a given bufnum **server** : SCServer, optional The server instance to establish the Buffer, by default use the SC default server .. rubric:: Notes For more information on Buffer commands, refer to the Server Command Reference in SC3. https://doc.sccode.org/Reference/Server-Command-Reference.html#Buffer%20Commands .. rubric:: Examples (see examples/buffer-examples.ipynb) >>> b = Buffer().load_file(...) >>> b = Buffer().load_data(...) >>> b = Buffer().alloc(...) >>> b = Buffer().load_asig(...) >>> b = Buffer().use_existing(...) >>> b = Buffer().copy(Buffer) :Attributes: **server** : the SCServer object to communicate with scsynth **_bufnum** : int buffer number = bufnum id on scsynth **_sr** : int the sampling rate of the buffer **_channels** : int number of channels of the buffer **_samples** : int buffer length = number of sample frames **_alloc_mode** : str ['file', 'alloc', 'data', 'existing', 'copy'] according to previously used generator, defaults to None **_allocated** : boolean True if Buffer has been allocated by any of the initialization methods **_path** : str path to the audio file used in load_file() .. !! processed by numpydoc !! **Overview:** .. autoapisummary:: :nosignatures: sc3nb.sc_objects.buffer.Buffer.read sc3nb.sc_objects.buffer.Buffer.alloc sc3nb.sc_objects.buffer.Buffer.load_data sc3nb.sc_objects.buffer.Buffer.load_collection sc3nb.sc_objects.buffer.Buffer.load_asig sc3nb.sc_objects.buffer.Buffer.use_existing sc3nb.sc_objects.buffer.Buffer.copy_existing sc3nb.sc_objects.buffer.Buffer.fill sc3nb.sc_objects.buffer.Buffer.gen sc3nb.sc_objects.buffer.Buffer.zero sc3nb.sc_objects.buffer.Buffer.gen_sine1 sc3nb.sc_objects.buffer.Buffer.gen_sine2 sc3nb.sc_objects.buffer.Buffer.gen_sine3 sc3nb.sc_objects.buffer.Buffer.gen_cheby sc3nb.sc_objects.buffer.Buffer.gen_copy sc3nb.sc_objects.buffer.Buffer.play sc3nb.sc_objects.buffer.Buffer.write sc3nb.sc_objects.buffer.Buffer.close sc3nb.sc_objects.buffer.Buffer.to_array sc3nb.sc_objects.buffer.Buffer.query sc3nb.sc_objects.buffer.Buffer.__repr__ sc3nb.sc_objects.buffer.Buffer.free sc3nb.sc_objects.buffer.Buffer._gen_flags .. py:method:: read(path: str, starting_frame: int = 0, num_frames: int = -1, channels: Optional[Union[int, Sequence[int]]] = None) -> Buffer Allocate buffer memory and read a sound file. If the number of frames argument num_frames is negative or zero, the entire file is read. :Parameters: **path** : string path name of a sound file. **starting_frame** : int starting frame in file **num_frames** : int number of frames to read **channels** : list | int channels and order of channels to be read from file. if only a int is provided it is loaded as only channel :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: alloc(size: int, sr: int = 44100, channels: int = 1) -> Buffer Allocate buffer memory. :Parameters: **size** : int number of frames **sr** : int sampling rate in Hz (optional. default = 44100) **channels** : int number of channels (optional. default = 1 channel) :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: load_data(data: numpy.ndarray, sr: int = 44100, mode: str = 'file', sync: bool = True) -> Buffer Allocate buffer memory and read input data. :Parameters: **data** : numpy array Data which should inserted **sr** : int, default: 44100 sample rate **mode** : 'file' or 'osc' Insert data via filemode ('file') or n_set OSC commands ('osc') Bundling is only supported for 'osc' mode and if sync is False. **sync: bool, default: True** Use SCServer.sync after sending messages when mode = 'osc' :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: load_collection(data: numpy.ndarray, mode: str = 'file', sr: int = 44100) -> Buffer Wrapper method of :func:`Buffer.load_data` .. !! processed by numpydoc !! .. py:method:: load_asig(asig: pya.Asig, mode: str = 'file') -> Buffer Create buffer from asig :Parameters: **asig** : pya.Asig asig to be loaded in buffer **mode** : str, optional Insert data via filemode ('file') or n_set OSC commands ('osc'), by default 'file' :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: use_existing(bufnum: int, sr: int = 44100) -> Buffer Creates a buffer object from already existing Buffer bufnum. :Parameters: **bufnum** : int buffer node id **sr** : int Sample rate :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: copy_existing(buffer: Buffer) -> Buffer Duplicate an existing buffer :Parameters: **buffer** : Buffer object Buffer which should be duplicated :Returns: **self** : Buffer the newly created Buffer object :Raises: RuntimeError If the Buffer is already allocated. .. !! processed by numpydoc !! .. py:method:: fill(start: int = 0, count: int = 0, value: float = 0) -> Buffer Fill range of samples with value(s). :Parameters: **start** : int or list int : sample starting index list : n*[start, count, value] list **count** : int number of samples to fill **value** : float value :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen(command: str, args: List[Any]) -> Buffer Call a command to fill a buffer. If you know, what you do -> you can use this method. :Parameters: **command** : str What fill command to use. **args** : List[Any] Arguments for command :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. seealso:: :obj:`gen_sine1`, :obj:`gen_sine2`, :obj:`gen_cheby`, :obj:`gen_cheby`, :obj:`gen_copy` .. .. !! processed by numpydoc !! .. py:method:: zero() -> Buffer Set buffer data to zero. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine1(amplitudes: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves & given amplitude :Parameters: **amplitudes** : list The first float value specifies the amplitude of the first partial, the second float value specifies the amplitude of the second partial, and so on. **normalize** : bool Normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, then the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set then the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine2(freq_amps: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves given list of [frequency, amplitude] lists :Parameters: **freq_amps** : list Similar to sine1 except that each partial frequency is specified explicitly instead of being an integer multiple of the fundamental. Non-integer partial frequencies are possible. **normalize** : bool If set, normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set, the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_sine3(freqs_amps_phases: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fill the buffer with sine waves & given a list of [frequency, amplitude, phase] entries. :Parameters: **freqs_amps_phases** : list Similar to sine2 except that each partial may have a nonzero starting phase. **normalize** : bool if set, normalize peak amplitude of wave to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set, the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_cheby(amplitudes: List[float], normalize: bool = False, wavetable: bool = False, clear: bool = False) -> Buffer Fills a buffer with a series of chebyshev polynomials, which can be defined as cheby(n) = amplitude * cos(n * acos(x)) :Parameters: **amplitudes** : list The first float value specifies the amplitude for n = 1, the second float value specifies the amplitude for n = 2, and so on **normalize** : bool If set, normalize the peak amplitude of the Buffer to 1.0. **wavetable** : bool If set, the buffer is written in wavetable format so that it can be read by interpolating oscillators. **clear** : bool If set the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: gen_copy(source: Buffer, source_pos: int, dest_pos: int, copy_amount: int) -> Buffer Copy samples from the source buffer to the destination buffer specified in the b_gen command. :Parameters: **source** : Buffer Source buffer object **source_pos** : int sample position in source **dest_pos** : int sample position in destination **copy_amount** : int number of samples to copy. If the number of samples to copy is negative, the maximum number of samples possible is copied. :Returns: **self** : Buffer the created Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: play(rate: float = 1, loop: bool = False, pan: float = 0, amp: float = 0.3) -> sc3nb.sc_objects.node.Synth Play the Buffer using a Synth :Parameters: **rate** : float, optional plackback rate, by default 1 **loop** : bool, optional if True loop the playback, by default False **pan** : int, optional pan position, -1 is left, +1 is right, by default 0 **amp** : float, optional amplitude, by default 0.3 :Returns: Synth Synth to control playback. :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: write(path: str, header: str = 'wav', sample: str = 'float', num_frames: int = -1, starting_frame: int = 0, leave_open: bool = False) -> Buffer Write buffer data to a sound file :Parameters: **path** : string path name of a sound file. **header** : string header format. Header format is one of: "aiff", "next", "wav", "ircam"", "raw" **sample** : string sample format. Sample format is one of: "int8", "int16", "int24", "int32", "float", "double", "mulaw", "alaw" **num_frames** : int number of frames to write. -1 means all frames. **starting_frame** : int starting frame in buffer **leave_open** : boolean Whether you want the buffer file left open. For use with DiskOut you will want this to be true. The file is created, but no frames are written until the DiskOut UGen does so. The default is false which is the correct value for all other cases. :Returns: **self** : Buffer the Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: close() -> Buffer Close soundfile after using a Buffer with DiskOut :Returns: **self** : Buffer the Buffer object :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: to_array() -> numpy.ndarray Return the buffer data as an array representation. :Returns: np.ndarray: Values of the buffer :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: query() -> BufferInfo Get buffer info. :Returns: Tuple: (buffer number, number of frames, number of channels, sampling rate) :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: __repr__() -> str Return repr(self). .. !! processed by numpydoc !! .. py:method:: free() -> None Free buffer data. :Raises: RuntimeError If the Buffer is not allocated yet. .. !! processed by numpydoc !! .. py:method:: _gen_flags(a_normalize=False, a_wavetable=False, a_clear=False) -> int Generate Wave Fill Commands flags from booleans according to the SuperCollider Server Command Reference. :Parameters: **a_normalize** : bool, optional Normalize peak amplitude of wave to 1.0, by default False **a_wavetable** : bool, optional If set, then the buffer is written in wavetable format so that it can be read by interpolating oscillators, by default False **a_clear** : bool, optional If set then the buffer is cleared before new partials are written into it. Otherwise the new partials are summed with the existing contents of the buffer, by default False :Returns: int Wave Fill Commands flags .. !! processed by numpydoc !!