Crate synthizer

Bindings to Synthizer. For documentation of the library itself, see the book. This documentation covers aspects specific to the Rust bindings which map to the C bindings in a relatively straightforward manner

Handles

Synthizer Handles are reference-counted pointers which work like Arc. All the objects in this library that correspond to Synthizer objects (e.g. BufferGenerator but not CustomStreamDef) impl Clone and internally contain a handle. So, e.g:

use synthizer as syz;
let ctx = syz::Context::new()?;
// Refers to the same context.
let ctx2 = ctx.clone();

Initialization

To initialize the library, use either initialize or the LibraryConfig type. These will give you a InitializationGuard which must be kept alive for the duration of the program. After the InitializationGuard goes out of scope, Synthizer functions all error.

Properties

Properties are modeled as a property() method which returns an intermediate object that has methods on it. For example, obj.playback_position().set(5.0). Object properties aren’t type checked but error if using an object of the wrong type at runtime. An internal trait, ToSyzHandle, is implemented for all library types.

Common Functionality

All Synthizer objects implement a set of common methods on their struct. When the Synthizer manual refers to things like syz_pause, this can be found as .pause() on all applicable objects.

Userdata

Synthizer supports userdata, which can be used to tie application entities to Synthizer objects via Arc<Any>. This is set by e.g. Handle::set_userdata. Note that unlike Synthizer itself, the Rust bindings have to put userdata behind a std::sync::RwLock to offer thread safety,.

Casting Objects

Synthizer itself is modeled as a hierarchy of “classes”. For example Source is a “base class” of all sources. This is handled in Rust via adding a cast_to method to all Synthizer types, which can be used to attempt to cast to other object types when possible. For example Source3D to Source, but also Handle to Source3D.

Where this cast is infallible, From impls are provided.

Custom Streams

Custom streams are possible via CustomStreamDef and register_stream_protocol. See the documentation on those types for more info. In general, it is possible to convert anything implementing std::io::Read and std::io::Seek to a custom stream by implementing CloseStream for that type or a wrapper struct thereof.

Optional Features

Synthizer has the following optional features:

• asset_lru: Enable support for asset_lru via AssetLruDecoder, which implements the asset_lru decoding traits.

Structs

• AngularPannedSource
• AutomationBatch
  Binds the Synthizer automation functionality.
• BiquadConfig
  Biquad filters. This is used primarily as the value to biquad properties. The member functions match the Synthizer C functions of the same name.
• BoolProperty
• Buffer
• BufferGenerator
• Context
  The Context represents an audio device.
• CustomStreamDef
  A definition for a custom stream. This can come from a variety of places and is consumed by e.g. StreamingGenerator::from_stream_handle, or returned as a result of the callback passed to register_stream_protocol.
• DeleteBehaviorConfig
• DeleteBehaviorConfigBuilder
  A builder for a DeleteBehaviorConfig.
• DirectSource
• Double3Property
• Double6Property
• DoubleProperty
• EnumProperty
  A property backed by a Synthizer enum.
• Error
• Event
• FastSineBankGenerator
• Generator
  Represents the generator “base class”. A From impl lets you get to this object from any kind of generator.
• GlobalEcho
• GlobalFdnReverb
• Handle
• InitializationGuard
  An InitializationGuard shuts Synthizer down when dropped, and must be kept alive for the duration of your program.
• IntProperty
  Representation of a property backed by an i32.
• LibraryConfig
  A builder to configure Synthizer initialization with non-default values. To initialize, call .initialize().
• NoiseGenerator
• ObjectProperty
• RouteConfig
  A Synthizer route, used to connect sources to effects. See Context::config_route or, if you want to avoid this type, Context::config_route_simple.
• RouteConfigBuilder
  A builder for an effect route. new and Default are the equivalent of syz_initRouteConfig, e.g. a builder representing the default route.
• ScalarPannedSource
• SineBankWave
• Source
  Represents the source “base class”. It is possible to convert to this type from any source, in order to use source-common functionality.
• Source3D
• StreamHandle
  A StreamHandle binds Synthizer custom streams, as well as other kinds of streaming functionality.
• StreamingGenerator

Enums

• DistanceModel
• ErrorKind
  An ErrorKind represents what kind of error Synthizer has given back. Currently, this is only Other, since Synthizer hasn’t yet defined error codes properly.
• EventType
• InterpolationType
• LogLevel
• NoiseType
• ObjectType
• PannerStrategy

Constants

• DEFAULT_Q
  Suggested default Q for filter design functions. If you don’t have a better idea what value of Q to use, this is what you want.

Traits

• CloseStream
  A trait which custom streams must implement in order to support closing.
• SeekableStream
  A Stream, but one which also implements Seek.
• Stream
  Marker trait for types which implement non-seekable streams.

Functions

• get_version
  Query the underlying Synthizer version, returning a (major, minor, patch) tuple. This isn’t the version of the crate, but of the bound library.
• initialize
  Initialize Synthizer, returning a InitializationGuard which must be kept alive for the duration of your program.
• register_stream_protocol
  register a custom protocol.

Type Definitions

• EchoTapConfig
  Re-exported Synthizer syz_EchoTapConfig type. Using this instead of a dedicated struct prevents needing to clone your taps on the way to Synthizer.
• Result