-
Notifications
You must be signed in to change notification settings - Fork 1
Configuration
bquence respects several compile-time settings defined in its configuration file, bqConfig.h. Please read the comments in that file in addition to this document for further clarification. If you need to customize any of these settings, just edit your local copy of bqConfig.h that is included in your project.
bquence requires the number of tracks and playheads in any bq::World to be specified at compile time.
constexpr unsigned int WORLD_NUM_TRACKS = 4;
constexpr unsigned int WORLD_NUM_PLAYHEADS = 2;Set WORLD_NUM_TRACKS to the maximum number of tracks you'll need available in any world, and WORLD_NUM_PLAYHEADS to the maximum number of playheads you'll need available in any world.
bquence uses a hybrid audio buffering method that loads several frames at the beginning of each clip for fast random access, and streams the rest of the clip from the hard drive for consistent sequential playback. This setup maintains low memory usage, by not loading entire audio files, while preventing dropouts as the playhead transitions from one clip to the next, by buffering the beginning of each clip.
bquence's buffering system is fully configurable, so if you notice audio dropouts or unusual system load while playing back sequences, you might want to try adjusting these settings:
constexpr unsigned int PRELOADER_NUM_FRAMES = 176400;
constexpr unsigned int STREAMER_CHUNK_NUM_FRAMES = 176400;
constexpr unsigned int STREAMER_NEXT_CHUNK_WINDOW_NUM_FRAMES = 176400;PRELOADER_NUM_FRAMES specifies the number of frames at the beginning of each clip that should be buffered in advance rather than streamed on-demand from disk. Increasing this parameter increases bquence's memory consumption proportionally to the number of clips that are contained in all sequences, but it decreases the chance that the audio engine will be missing frames while the I/O engine switches between open audio files (important on old non-SSD drives).
STREAMER_CHUNK_NUM_FRAMES specifies the number of frames that, when streaming, the I/O thread will decode in one chunk before sending to the audio thread. Increasing this number increases the CPU load and latency between each streaming decode operation, but it decreases the amount of signaling required between the I/O and audio threads. Increasing this number also decreases the number of streaming decode operations proportionally to the amount by which this value was increased, so the CPU load and latency trade-offs should cancel out under normal usage conditions.
This setting also slightly affects seek latency, since whenever a seek occurs, the audio thread must wait for the I/O thread to decode the given number of chunks before it has any audio data to play back.
STREAMER_NEXT_CHUNK_WINDOW_NUM_FRAMES specifies the minimum number of frames that must be stored in the audio thread's cache before a streaming decode operation is triggered on the I/O thread.
All of these numbers here will be affected by the sample rates of output devices. For example, with an output sample rate of 44.1 kHz and an SSD or modern hard disk, these settings should enable bquence to run stably. However, if you plan to output at 192 kHz, you might consider increasing these numbers by four or five times.
(Consider the STREAMER_NEXT_CHUNK_WINDOW_NUM_FRAMES setting: at 44.1 kHz, bquence has 88,200 / 44,100 = 2 seconds to decode any audio data before it is needed by the audio thread. At 192 kHz, bquence only has 88,200 / 192,000 ≈ 0.46 seconds to decode audio data. That is unreliable under system strain or large numbers of tracks).
constexpr unsigned int ENGINE_MAX_NUM_POOL_MSGS = 1024;ENGINE_MAX_NUM_POOL_MSGS specifies the maximum number of messages that are pre-allocated for each thread to pass to each other. 1024 is a safe value unless you're planning to perform thousands of arrangement editing operations in an extremely short time-span, or you've set STREAMER_NEXT_CHUNK_WINDOW_NUM_FRAMES to a much greater value than STREAMER_CHUNK_NUM_FRAMES, in which case the I/O thread might run out of messages to queue these edits or decoded chunks for processing.
constexpr bool TIMESTRETCH_USE_QUICKSEEK = true;
constexpr int TIMESTRETCH_SEQUENCE_MS = -1;
constexpr int TIMESTRETCH_SEEKWINDOW_MS = -1;
constexpr int TIMESTRETCH_OVERLAP_MS = -1;bquence internally uses SoundTouch to independently adjust pitch and tempo of audio files, keeping everything synchronized to the session's master tempo. The settings above are passed directly to each of bquence's SoundTouch instances upon their initialization. A value of -1 indicates that SoundTouch should use a default (automatically calculated) value. Please refer to sections 3.4 and 3.5 of the SoundTouch README for more information.