An AudioRegion represents a region of audio within a Track. More...

#include <src/gui/dsp/audio_region.h>

Inheritance diagram for AudioRegion:

[legend]

Collaboration diagram for AudioRegion:

[legend]

Public Types
using	BitDepth = AudioClip::BitDepth

Public Types inherited from RegionImpl< AudioRegion >
using	RegionTPtr

using	ChildT

using	ChildTPtr

Public Types inherited from ArrangerObject
enum class	ResizeType { Normal , Loop , Fade , Stretch , StretchTempoChange }
	Flag used in some functions. More...

enum class	Type { MidiRegion , AudioRegion , ChordRegion , AutomationRegion , MidiNote , ChordObject , ScaleObject , Marker , AutomationPoint }
	The type of the object. More...

enum class	Flags { NonProject = 1 << 0 }
	Flags. More...

enum class	PositionType { Start , End , ClipStart , LoopStart , LoopEnd , FadeIn , FadeOut }

using	SelectionStatusGetter = std::function<bool (const Uuid &)>

using	Position = zrythm::dsp::Position

using	ArrangerObjectPtr = ArrangerObject *

Public Types inherited from NamedObject
using	NameValidator = std::function<bool (const utils::Utf8String &)>

Public Types inherited from ColoredObject
using	Color = zrythm::utils::Color

Public Member Functions
	AudioRegion (ArrangerObjectRegistry &obj_registry, TrackResolver track_resolver, AudioClipResolverFunc clip_resolver, QObject *parent=nullptr) noexcept

AudioClip *	get_clip () const
	Returns the audio clip associated with the Region.

auto	get_clip_id () const

void	set_clip_id (const AudioClip::Uuid &clip_id)
	Sets the clip ID on the region and updates any references.

bool	get_muted (bool check_parent) const override
	Gets the mute status of the object.

bool	get_musical_mode () const
	Returns whether the region is effectively in musical mode.

void	replace_frames (const utils::audio::AudioBuffer &src_frames, unsigned_frame_t start_frame)
	Replaces the region's frames starting from `start_frame` with `frames`.

void	fill_stereo_ports (const EngineProcessTimeInfo &time_nfo, std::pair< AudioPort &, AudioPort & > stereo_ports) const
	Fills audio data from the region.

float	detect_bpm (std::vector< float > &candidates)

bool	fix_positions (dsp::FramesPerTick frames_per_tick)
	Fixes off-by-one rounding errors when changing BPM or sample rate which result in the looped part being longer than there are actual frames in the clip.

bool	validate (bool is_project, dsp::FramesPerTick frames_per_tick) const override
	Validates the arranger object.

void	init_after_cloning (const AudioRegion &other, ObjectCloneType clone_type) override
	Initializes the cloned object.

void	prepare_to_play (size_t max_expected_samples)

void	release_resources ()

Public Member Functions inherited from RegionImpl< AudioRegion >
void	append_children (this AudioRegion &self, std::vector< RegionOwnedObject * > &children)
	Fills the given vector with all the children of this region.

void	fill_midi_events (TrackPtrVariant track_var, const EngineProcessTimeInfo &time_nfo, bool note_off_at_end, bool is_note_off_for_loop_or_region_end, dsp::MidiEventVector &midi_events) const
	Fills MIDI event queue from this MIDI or Chord region.

auto	get_object_ptr (const ArrangerObject::Uuid id) const

auto	get_object_ptr (const ArrangerObjectUuidReference &id) const

auto &	get_arranger_object_registry () const

auto &	get_arranger_object_registry ()

void	remove_all_children (this AudioRegion &self)
	Removes all children objects from the region.

bool	get_muted (bool check_parent) const override
	Gets the mute status of the object.

ArrangerObjectPtrVariant	add_clone_to_project (bool fire_events) const final
	Appends the ArrangerObject to where it belongs in the project (eg, a Track), without taking into account its previous index (eg, before deletion if undoing).

ArrangerObjectPtrVariant	insert_clone_to_project () const final
	Inserts the object where it belongs in the project (eg, a Track).

void	set_link_group (int group_idx, bool update_identifier)
	Sets the link group to the region.

void	update_identifier (this AudioRegion &self)
	Disconnects the region and anything using it.

void	unlink ()
	Removes the link group from the region, if any.

bool	are_members_valid (bool is_project, dsp::FramesPerTick frames_per_tick) const

void	stretch (double ratio)
	Stretch the region's contents.

void	create_link_group_if_none ()

Public Member Functions inherited from Region
bool	is_midi () const

bool	is_audio () const

bool	is_automation () const

bool	is_chord () const

RegionLinkGroup *	get_link_group ()
	Returns the region's link group.

bool	has_link_group () const

signed_frame_t	timeline_frames_to_local (signed_frame_t timeline_frames, bool normalize) const
	Converts frames on the timeline (global) to local frames (in the clip).

void	get_frames_till_next_loop_or_end (signed_frame_t timeline_frames, signed_frame_t ret_frames, bool is_loop) const
	Returns the number of frames until the next loop end point or the end of the region.

void	update_link_group ()
	Updates all other regions in the region link group, if any.

bool	is_recording ()
	Returns if this region is currently being recorded onto.

Public Member Functions inherited from ArrangerObject
auto	get_type () const

bool	is_start_hit_by_range (const dsp::Position &start, const dsp::Position &end, bool range_start_inclusive=true, bool range_end_inclusive=false) const
	Returns whether the given object is hit by the given range.

bool	is_start_hit_by_range (const signed_frame_t global_frames_start, const signed_frame_t global_frames_end, bool range_start_inclusive=true, bool range_end_inclusive=false) const

void	set_parent_on_base_qproperties (QObject &derived)
	Set the parent on QObject's that are children of this class.

auto	get_position () const
	Getter.

void	position_setter_validated (const dsp::Position &pos, dsp::TicksPerFrame ticks_per_frame)
	The setter is for use in e.g.

void	set_position_unvalidated (const dsp::Position &pos)

bool	is_position_valid (const dsp::Position &pos, PositionType pos_type, dsp::TicksPerFrame ticks_per_frame) const
	Returns if the given Position is valid.

bool	set_position (const dsp::Position &pos, PositionType pos_type, bool validate, dsp::TicksPerFrame ticks_per_frame)
	Sets the given position on the object, optionally attempting to validate before.

void	move (double ticks, dsp::FramesPerTick frames_per_tick)
	Moves the object by the given amount of ticks.

void	set_track_id (const TrackUuid &track_id)

void	set_track_id (std::optional< TrackUuid > track_id)

void	unset_track_id ()

void	update_positions (bool from_ticks, bool bpm_change, dsp::FramesPerTick frames_per_tick)
	Updates the positions in each child recursively.

auto	get_track () const
	Returns the Track this ArrangerObject is in.

std::optional< TrackUuid >	get_track_id () const

std::optional< ArrangerObjectPtrVariant >	remove_from_project (bool free_obj, bool fire_events=false)
	Removes the object (which can be obtained from find_in_project()) from its parent in the project.

void	set_selection_status_getter (SelectionStatusGetter getter)

void	unset_selection_status_getter ()

virtual bool	is_deletable () const
	Returns whether the given object is deletable or not (eg, start marker).

Public Member Functions inherited from zrythm::utils::UuidIdentifiableObject< ArrangerObject >
	UuidIdentifiableObject (const Uuid &id)

	UuidIdentifiableObject (const UuidIdentifiableObject &other)=default

	UuidIdentifiableObject (UuidIdentifiableObject &&other)=default

UuidIdentifiableObject &	operator= (const UuidIdentifiableObject &other)=default

UuidIdentifiableObject &	operator= (UuidIdentifiableObject &&other)=default

auto	get_uuid () const

void	copy_members_from (const UuidIdentifiableObject &other)

Public Member Functions inherited from NamedObject
	NamedObject (NameValidator validator=[](const utils::Utf8String &) { return true;})

utils::Utf8String	get_name () const
	Returns the name of the object.

void	gen_escaped_name ()
	Generates the escaped name for the object.

void	set_name (this auto &&self, const utils::Utf8String &name)
	Sets the name of the object.

void	generate_name_from_automation_track (this auto &self, const auto &track, const auto &at)

void	generate_name_from_track (this auto &self, const auto &track)

void	generate_name (this auto &self, std::optional< utils::Utf8String > base_name, const auto at, const auto track)

void	set_name_with_action (const utils::Utf8String &name)
	Changes the name and adds an action to the undo stack.

utils::Utf8String	gen_human_friendly_name () const final
	Generates a human readable name for the object.

Public Member Functions inherited from MuteableObject
void	set_muted (bool muted, bool fire_events)
	Sets the mute status of the object.

Public Member Functions inherited from LoopableObject
int	get_num_loops (bool count_incomplete) const
	Returns the number of loops in the ArrangerObject, optionally including incomplete ones.

const auto &	get_clip_start_pos () const
	Getter.

const auto &	get_loop_start_pos () const
	Getter.

const auto &	get_loop_end_pos () const
	Getter.

void	clip_start_position_setter_validated (const dsp::Position &pos, dsp::TicksPerFrame ticks_per_frame)
	The setter is for use in e.g.

void	loop_start_position_setter_validated (const dsp::Position &pos, dsp::TicksPerFrame ticks_per_frame)
	The setter is for use in e.g.

void	loop_end_position_setter_validated (const dsp::Position &pos, dsp::TicksPerFrame ticks_per_frame)
	The setter is for use in e.g.

void	set_loop_start_position_unvalidated (const dsp::Position &pos)

void	set_loop_end_position_unvalidated (const dsp::Position &pos)

void	set_clip_start_position_unvalidated (const dsp::Position &pos)

double	get_loop_length_in_ticks () const
	Returns the length of the loop in ticks.

auto	get_loop_length_in_frames () const
	Returns the length of the loop in frames.

bool	is_looped () const

Public Member Functions inherited from BoundedObject
auto	get_end_position () const
	Getter.

void	parent_base_qproperties (QObject &derived)

void	end_position_setter_validated (const dsp::Position &pos, dsp::TicksPerFrame ticks_per_frame)
	The setter is for use in e.g.

void	set_end_position_unvalidated (const dsp::Position &pos)

auto	get_length_in_ticks () const
	Returns the length in ticks.

auto	get_length_in_frames () const
	Returns the length in frames.

void	resize (bool left, ResizeType type, double ticks, bool during_ui_action)
	Resizes the object on the left side or right side by given amount of ticks, for objects that do not have loops (currently none?

template<typename SelfT> requires (FinalArrangerObjectSubclass<SelfT>)
void	set_start_pos_full_size (this SelfT &self, const Position &pos, dsp::FramesPerTick frames_per_tick)
	Sets the end position of the ArrangerObject and also sets the loop end and fade out (if object supports those) so that they are at the end.

template<typename SelfT> requires (FinalArrangerObjectSubclass<SelfT>)
void	set_end_pos_full_size (this SelfT &self, const dsp::Position &pos, dsp::FramesPerTick frames_per_tick)
	Sets the end position of the ArrangerObject and also sets the loop end and fade out (if object supports those) to that position.

bool	is_hit (const dsp::Position &pos, bool object_end_pos_inclusive=false) const
	Returns whether the object is hit by the given position (local position if non-timeline object).

bool	is_hit (const signed_frame_t frames, bool object_end_pos_inclusive=false) const

bool	is_hit_by_range (const dsp::Position &start, const dsp::Position &end, bool range_start_inclusive=true, bool range_end_inclusive=false, bool object_end_pos_inclusive=false) const
	Returns whether the given object is hit by the given range.

bool	is_hit_by_range (signed_frame_t global_frames_start, signed_frame_t global_frames_end, bool range_start_inclusive=true, bool range_end_inclusive=false, bool object_end_pos_inclusive=false) const

virtual bool	is_inside_range (const dsp::Position &start, const dsp::Position &end) const
	Checks if any part of the object is hit by the given range.

Public Member Functions inherited from ColoredObject
QColor	get_effective_color () const
	Returns the color of the object if set, otherwise the owner track's color.

Public Member Functions inherited from LaneOwnedObject
	Z_DISABLE_COPY_MOVE (LaneOwnedObject)

bool	is_inserted_in_lane () const

template<typename SelfT> requires std::is_same_v<SelfT, MidiRegion>
MidiLane &	get_lane (this const SelfT &self)

template<typename SelfT> requires std::is_same_v<SelfT, AudioRegion>
AudioLane &	get_lane (this const SelfT &self)

template<typename SelfT>
auto	get_lane_index (this const SelfT &self)

void	set_lane (TrackLanePtrVariant lane)
	Sets the track lane.

void	copy_members_from (const LaneOwnedObject &other, ObjectCloneType clone_type)

Public Member Functions inherited from FadeableObject
void	get_fade_in_pos (Position *pos) const
	Getter.

void	get_fade_out_pos (Position *pos) const
	Getter.

void	set_fade_in_position_unvalidated (const dsp::Position &pos)

void	set_fade_out_position_unvalidated (const dsp::Position &pos)

Public Member Functions inherited from ICloneable< AudioRegion >
std::unique_ptr< AudioRegion >	clone_unique (ObjectCloneType clone_type=ObjectCloneType::Snapshot, Args &&... args) const

std::shared_ptr< AudioRegion >	clone_shared (ObjectCloneType clone_type=ObjectCloneType::Snapshot, Args &&... args) const

AudioRegion *	clone_raw_ptr (ObjectCloneType clone_type=ObjectCloneType::Snapshot, Args &&... args) const

AudioRegion *	clone_qobject (QObject *parent, ObjectCloneType clone_type=ObjectCloneType::Snapshot, Args &&... args) const

QScopedPointer< AudioRegion >	clone_unique_qobject (QObject *parent, ObjectCloneType clone_type=ObjectCloneType::Snapshot, Args &&... args) const

Data Fields
AudioClipResolverFunc	clip_resolver_

AudioClip::Uuid	clip_id_
	ID of the associated AudioClip to be resolved with clip_resolver_.

float	gain_ = 1.0f
	Whether to read the clip from the pool (used in most cases).

MusicalMode	musical_mode_ {}
	Clip to read frames from, if not from the pool.

std::unique_ptr< juce::AudioSampleBuffer >	tmp_buf_
	Temporary buffer used during audio processing.

Data Fields inherited from Region
ArrangerObjectRegistry &	object_registry_

std::optional< int >	link_group_

int	bounce_ = 0
	Set to ON during bouncing if this region should be included.

bool	stretching_ = false
	Whether currently running the stretching algorithm.

double	stretch_ratio_ = 1.0
	Used during arranger UI overlay actions.

double	before_length_ = 0.0
	The length before stretching, in ticks.

Data Fields inherited from ArrangerObject
Flags	flags_ {}
	Track this object belongs to (cache to be set during graph calculation).

Data Fields inherited from MuteableObject
bool	muted_ = false
	Whether muted or not.

Data Fields inherited from LoopableObject
dsp::Position	clip_start_pos_
	Start position of the clip loop, relative to the object's start.

dsp::Position	loop_start_pos_
	Loop start Position relative to the object's start.

dsp::Position	loop_end_pos_
	End position of the clip loop, relative to the object's start.

Data Fields inherited from BoundedObject
PositionProxy *	end_pos_ = nullptr
	End Position, if the object has one.

Data Fields inherited from ColoredObject
Color	color_
	Color independent of owner (Track/Region etc.).

bool	use_color_ = false
	Whether to use the custom color.

Data Fields inherited from LaneOwnedObject
std::optional< int >	index_in_prev_lane_
	Object's index in the previous lane (before being moved to a new lane/track).

Data Fields inherited from FadeableObject
Position	fade_in_pos_
	Fade in position, relative to the object's start.

Position	fade_out_pos_
	Fade out position, relative to the object's start.

dsp::CurveOptions	fade_in_opts_
	Fade in curve options.

dsp::CurveOptions	fade_out_opts_
	Fade out curve options.

Data Fields inherited from ICloneable< AudioRegion >
friend	Derived

Friends
void	to_json (nlohmann::json &j, const AudioRegion &region)

void	from_json (const nlohmann::json &j, AudioRegion &region)

Additional Inherited Members
Static Public Member Functions inherited from RegionImpl< AudioRegion >
static constexpr bool	is_midi ()

static constexpr bool	is_audio ()

static constexpr bool	is_automation ()

static constexpr bool	is_chord ()

static constexpr bool	is_laned ()

static constexpr bool	has_children ()

static AudioRegion *	at_position (const Track track, const AutomationTrack at, dsp::Position pos)
	Returns the region at the given position in the given Track.

Static Public Member Functions inherited from Region
static std::optional< ArrangerObjectPtrVariant >	get_at_pos (dsp::Position pos, Track track, AutomationTrack at, bool include_region_end=false)
	Returns the region at the given position, if any.

Static Public Attributes inherited from ArrangerObject
static constexpr double	DEFAULT_NUDGE_TICKS = 0.1

Protected Member Functions inherited from Region
	Region (ArrangerObjectRegistry &object_registry)

void	copy_members_from (const Region &other, ObjectCloneType clone_type)

Protected Member Functions inherited from TimelineObject
void	copy_members_from (const TimelineObject &other, ObjectCloneType clone_type)

Protected Member Functions inherited from ArrangerObject
	ArrangerObject (Type type, TrackResolver track_resolver) noexcept

void	copy_members_from (const ArrangerObject &other, ObjectCloneType clone_type)

bool	are_members_valid (bool is_project, dsp::FramesPerTick frames_per_tick) const
	To be called by validate() implementations.

Protected Member Functions inherited from NamedObject
void	copy_members_from (const NamedObject &other, ObjectCloneType clone_type)

Protected Member Functions inherited from MuteableObject
void	copy_members_from (const MuteableObject &other, ObjectCloneType clone_type)

Protected Member Functions inherited from LoopableObject
void	copy_members_from (const LoopableObject &other, ObjectCloneType clone_type)

bool	are_members_valid (bool is_project, dsp::FramesPerTick frames_per_tick) const

Protected Member Functions inherited from BoundedObject
void	copy_members_from (const BoundedObject &other, ObjectCloneType clone_type)

bool	are_members_valid (bool is_project, dsp::FramesPerTick frames_per_tick) const

Protected Member Functions inherited from ColoredObject
void	copy_members_from (const ColoredObject &other, ObjectCloneType clone_type)

template<typename Derived>
void	init_colored_object (this Derived &self)

Protected Member Functions inherited from FadeableObject
void	copy_members_from (const FadeableObject &other, ObjectCloneType clone_type)

bool	are_members_valid (bool is_project, dsp::FramesPerTick frames_per_tick) const

Protected Attributes inherited from ArrangerObject
TrackResolver	track_resolver_

PositionProxy *	pos_ = nullptr
	Position (or start Position if the object has length).

std::optional< TrackUuid >	track_id_
	ID of the track this object belongs to.

std::optional< SelectionStatusGetter >	selection_status_getter_
	Whether part of an auditioner track.

Protected Attributes inherited from NamedObject
utils::Utf8String	name_
	Name to be shown on the widget.

utils::Utf8String	escaped_name_
	Escaped name for drawing.

NameValidator	name_validator_

Detailed Description

An AudioRegion represents a region of audio within a Track.

It is responsible for managing the audio data, handling playback, and providing various operations on the audio region.

The AudioRegion class inherits from Region, LaneOwnedObject, and FadeableObject, allowing it to be positioned within a Track, owned by a specific Lane, and have fades applied to it.

The class provides methods for getting the associated AudioClip, setting the clip ID, replacing the audio frames, and filling the audio data into StereoPorts for playback. It also includes various properties related to audio stretching, gain, and musical mode.

Definition at line 37 of file audio_region.h.

Member Typedef Documentation

◆ BitDepth

using AudioRegion::BitDepth = AudioClip::BitDepth

Definition at line 50 of file audio_region.h.

Member Function Documentation

◆ fill_stereo_ports()

void AudioRegion::fill_stereo_ports	(	const EngineProcessTimeInfo &	time_nfo,
		std::pair< AudioPort &, AudioPort & >	stereo_ports ) const

Fills audio data from the region.

Note: The caller already splits calls to this function at each sub-loop inside the region, so region loop related logic is not needed.

Parameters

stereo_ports StereoPorts to fill.

◆ fix_positions()

bool AudioRegion::fix_positions ( dsp::FramesPerTick frames_per_tick )

Fixes off-by-one rounding errors when changing BPM or sample rate which result in the looped part being longer than there are actual frames in the clip.

Parameters

frames_per_tick Frames per tick used when validating audio regions. Passing 0 will use the value from the current engine.

Returns: Whether positions were adjusted.

◆ get_clip_id()

auto AudioRegion::get_clip_id ( ) const

inline

Definition at line 64 of file audio_region.h.

◆ get_muted()

bool AudioRegion::get_muted ( bool check_parent ) const

overridevirtual

Gets the mute status of the object.

Parameters

check_parent Whether to check parent (parent region or parent track lane if region), otherwise only whether this object itself is muted is returned. This will take the solo status of other lanes if true and if this is a region that can have lanes.

Reimplemented from MuteableObject.

◆ init_after_cloning()

void AudioRegion::init_after_cloning	(	const AudioRegion &	other,
		ObjectCloneType	clone_type )

overridevirtual

Initializes the cloned object.

Note: Only final classes should implement this.

Exceptions

ZrythmException If the object could not be cloned.

Implements ICloneable< AudioRegion >.

◆ replace_frames()

void AudioRegion::replace_frames	(	const utils::audio::AudioBuffer &	src_frames,
		unsigned_frame_t	start_frame )

Replaces the region's frames starting from start_frame with frames.

Warning: Not realtime safe.

Parameters

frames	Source frames.
start_frame	Frame to start copying to (`src_frames` are always copied from the start).

Exceptions

ZrythmException if the frames couldn't be replaced.

◆ set_clip_id()

void AudioRegion::set_clip_id ( const AudioClip::Uuid & clip_id )

inline

Sets the clip ID on the region and updates any references.

Definition at line 70 of file audio_region.h.

◆ validate()

bool AudioRegion::validate	(	bool	is_project,
		dsp::FramesPerTick	frames_per_tick ) const

overridevirtual

Validates the arranger object.

Parameters

frames_per_tick Frames per tick used when validating audio regions. Passing 0 will use the value from the current engine.

Returns: Whether valid.

Must only be implemented by final objects.

Implements ArrangerObject.

Friends And Related Symbol Documentation

◆ from_json

void from_json	(	const nlohmann::json &	j,
		AudioRegion &	region )

friend

Definition at line 149 of file audio_region.h.

◆ to_json

void to_json	(	nlohmann::json &	j,
		const AudioRegion &	region )

friend

Definition at line 136 of file audio_region.h.

Field Documentation

◆ clip_id_

AudioClip::Uuid AudioRegion::clip_id_

ID of the associated AudioClip to be resolved with clip_resolver_.

Definition at line 167 of file audio_region.h.

◆ clip_resolver_

AudioClipResolverFunc AudioRegion::clip_resolver_

Definition at line 164 of file audio_region.h.

◆ gain_

float AudioRegion::gain_ = 1.0f

Whether to read the clip from the pool (used in most cases).

Gain to apply to the audio (amplitude 0.0-2.0).

Definition at line 175 of file audio_region.h.

◆ musical_mode_

MusicalMode AudioRegion::musical_mode_ {}

Clip to read frames from, if not from the pool.

Musical mode setting.

Definition at line 183 of file audio_region.h.

◆ tmp_buf_

std::unique_ptr<juce::AudioSampleBuffer> AudioRegion::tmp_buf_

Temporary buffer used during audio processing.

Definition at line 188 of file audio_region.h.

The documentation for this class was generated from the following file:

src/gui/dsp/audio_region.h

Public Types

Public Member Functions

Data Fields

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ BitDepth

Member Function Documentation

◆ fill_stereo_ports()

◆ fix_positions()

◆ get_clip_id()

◆ get_muted()

◆ init_after_cloning()

◆ replace_frames()

◆ set_clip_id()

◆ validate()

Friends And Related Symbol Documentation

◆ from_json

◆ to_json

Field Documentation

◆ clip_id_

◆ clip_resolver_

◆ gain_

◆ musical_mode_

◆ tmp_buf_