Struct reaper_medium::Reaper

pub struct Reaper<UsageScope = MainThreadScope> { /* private fields */ }

This is the main access point for most REAPER functions.

Basics

You can obtain an instance of this struct by calling ReaperSession::reaper(). This unlocks all functions which are safe to execute in the main thread. If you want access to the functions which are safe to execute in the real-time audio thread, call ReaperSession::create_real_time_reaper() instead. REAPER functions which are related to registering/unregistering things are located in ReaperSession.

Please note that this struct contains nothing but function pointers, so you are free to clone it, e.g. in order to make all functions accessible somewhere else. This is sometimes easier than passing references around. Don’t do it too often though. It’s just a bitwise copy of all function pointers, but there are around 800 of them, so each copy will occupy about 7 kB of memory on a 64-bit system.

Panics

Don’t assume that all REAPER functions exposed here are always available. It’s possible that the user runs your plug-in in an older version of REAPER where a function is missing. See the documentation of low-level Reaper for ways how to deal with this.

Work in progress

Many functions which are available in the low-level API have not been lifted to the medium-level API yet. Unlike the low-level API, the medium-level one is hand-written and probably a perpetual work in progress. If you can’t find the function that you need, you can always resort to the low-level API by navigating to low(). Of course you are welcome to contribute to bring the medium-level API on par with the low-level one.

Design

What’s the <MainThreadScope> in Reaper<MainThreadScope> about?

In REAPER and probably many other DAWs there are at least two important threads:

1. The main thread (responsible for things like UI, driven by the UI main loop).
2. The real-time audio thread (responsible for processing audio and MIDI buffers, driven by the audio hardware)

Most functions offered by REAPER are only safe to be executed in the main thread. If you execute them in another thread, REAPER will crash. Or worse: It will seemingly work on your machine and crash on someone else’s. There are also a few functions which are only safe to be executed in the audio thread. And there are also very few functions which are safe to be executed from any thread (thread-safe).

There’s currently no way to make sure at compile time that a function is called in the correct thread. Of course that would be the best. In an attempt to still let the compiler help you a bit, the traits MainThreadOnly and RealTimeAudioThreadOnly have been introduced. They are marker traits which are used as type bound on each method which is not thread-safe. So depending on the context we can expose an instance of Reaper which has only functions unlocked which are safe to be executed from e.g. the real-time audio thread. The compiler will complain if you attempt to call a real-time-audio-thread-only method on Reaper<MainThreadScope> and vice versa.

Of course that technique can’t prevent anyone from acquiring a main-thread only instance and use it in the audio hook. But still, it adds some extra safety.

The alternative to tagging functions via marker traits would have been to implement e.g. audio-thread-only functions in a trait CallableFromRealTimeAudioThread as default functions and create a struct that inherits those default functions. Disadvantage: Consumer always would have to bring the trait into scope to see the functions. That’s confusing. It also would provide less amount of safety.

Why no fail-fast at runtime when calling audio-thread-only functions from wrong thread?

At the moment, there’s a fail fast (panic) when attempting to execute main-thread-only functions from the wrong thread. This prevents “it works on my machine” scenarios. However, this is currently not being done the other way around (when executing real-time-audio-thread-only functions from the wrong thread) because of possible performance implications. Latter scenario should also be much more unlikely. Maybe we can introduce it in future in order to really avoid undefined behavior even for those methods (which the lack of unsafe suggests). Checking the thread ID is a very cheap operation (a few nano seconds), maybe even in the real-time audio thread.

Implementations

impl Reaper<MainThreadScope>

pub fn make_available_globally(reaper: Reaper<MainThreadScope>)

Makes the given instance available globally.

After this has been called, the instance can be queried globally using get().

This can be called once only. Subsequent calls won’t have any effect!

pub fn get() -> &'static Reaper<MainThreadScope>

Gives access to the instance which you made available globally before.

Panics

This panics if make_available_globally() has not been called before.

impl<UsageScope> Reaper<UsageScope>

pub fn low(&self) -> &Reaper

Gives access to the low-level Reaper instance.

pub fn plugin_context(&self) -> PluginContext<'_, UsageScope>

Returns the plug-in context.

pub fn enum_projects(
    &self,
    project_ref: ProjectRef,
    buffer_size: u32
) -> Option<EnumProjectsResult>where
    UsageScope: AnyThread,

Returns the requested project and optionally its file name.

With buffer_size you can tell REAPER how many bytes of the file name you want. If you are not interested in the file name at all, pass 0.

Threading

If buffer_size > 0, this must be called from the main thread (panics if not).

If buffer_size == 0, this may also be called from a real-time or worker thread, not from your own thread (this won’t be checked!)

Example

use reaper_medium::ProjectRef::Tab;

let result = session.reaper().enum_projects(Tab(4), 256).ok_or("No such tab")?;
let project_dir = result.file_path.ok_or("Project not saved yet")?.parent();

pub fn get_track(
    &self,
    project: ProjectContext,
    track_index: u32
) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Returns the track at the given index.

Panics

Panics if the given project is not valid anymore.

Example

use reaper_medium::ProjectContext::CurrentProject;

let track = session.reaper().get_track(CurrentProject, 3).ok_or("No such track")?;

pub unsafe fn get_track_unchecked(
    &self,
    project: ProjectContext,
    track_index: u32
) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Like get_track() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_media_item(
    &self,
    project: ProjectContext,
    item_index: u32
) -> Option<MediaItem>where
    UsageScope: MainThreadOnly,

Returns the item at the given index.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_media_item_unchecked(
    &self,
    project: ProjectContext,
    item_index: u32
) -> Option<MediaItem>where
    UsageScope: MainThreadOnly,

Like get_media_item() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn validate_ptr_2<'a>(
    &self,
    project: ProjectContext,
    pointer: impl Into<ReaperPointer<'a>>
) -> boolwhere
    UsageScope: AnyThread,

Checks if the given pointer is still valid.

Example

use reaper_medium::ProjectContext::CurrentProject;

let track = session.reaper().get_track(CurrentProject, 0).ok_or("No track")?;
let track_is_valid = session.reaper().validate_ptr_2(CurrentProject, track);
assert!(track_is_valid);

Returns true if the pointer is a valid object of the correct type in the given project. The project is ignored if the pointer itself is a project.

pub fn validate_ptr<'a>(&self, pointer: impl Into<ReaperPointer<'a>>) -> boolwhere
    UsageScope: AnyThread,

Checks if the given pointer is still valid.

Returns true if the pointer is a valid object of the correct type in the current project.

pub fn update_timeline(&self)where
    UsageScope: MainThreadOnly,

Redraws the arrange view and ruler.

pub fn update_arrange(&self)where
    UsageScope: MainThreadOnly,

Redraws the arrange view.

pub fn track_list_adjust_windows_minor(&self)where
    UsageScope: MainThreadOnly,

Updates the track list after a minor change.

pub fn track_list_adjust_windows_major(&self)where
    UsageScope: MainThreadOnly,

Updates the track list after a major change.

pub fn show_console_msg<'a>(&self, message: impl Into<ReaperStringArg<'a>>)where
    UsageScope: MainThreadOnly,

Shows a message to the user in the ReaScript console.

This is also useful for debugging. Send “\n” for newline and “” to clear the console.

pub unsafe fn get_set_media_track_info(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey<'_>,
    new_value: *mut c_void
) -> *mut c_voidwhere
    UsageScope: MainThreadOnly,

Gets or sets a track attribute.

Returns the current value if new_value is null_mut().

It’s recommended to use one of the convenience functions instead. They all start with get_set_media_track_info_ and are more type-safe.

Safety

REAPER can crash if you pass an invalid track or invalid new value.

pub unsafe fn get_set_media_item_take_info(
    &self,
    take: MediaItemTake,
    attribute_key: TakeAttributeKey<'_>,
    new_value: *mut c_void
) -> *mut c_voidwhere
    UsageScope: MainThreadOnly,

Gets or sets a take attribute.

Returns the current value if new_value is null_mut().

It’s recommended to use one of the convenience functions instead. They all start with get_set_media_item_take_info_ and are more type-safe.

Safety

REAPER can crash if you pass an invalid take or invalid new value.

pub unsafe fn set_media_item_take_info_value(
    &self,
    take: MediaItemTake,
    attribute_key: TakeAttributeKey<'_>,
    new_value: f64
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets a take attribute as numerical value.

Errors

Returns an error if an invalid (e.g. non-numerical) track attribute key is passed.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_item_take_info_set_source(
    &self,
    take: MediaItemTake,
    source: OwnedPcmSource
) -> Option<OwnedPcmSource>where
    UsageScope: MainThreadOnly,

Convenience function which sets the take’s source (P_SOURCE).

Returns the previous source in case the take had a source assigned.

Safety

REAPER can crash if you pass an invalid take.

pub unsafe fn get_set_media_track_info_get_par_track(
    &self,
    track: MediaTrack
) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s parent track (P_PARTRACK).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_project(
    &self,
    track: MediaTrack
) -> Option<ReaProject>where
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s parent project (P_PROJECT).

In REAPER < 5.95 this returns None.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_name<R>(
    &self,
    track: MediaTrack,
    use_name: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Convenience function which grants temporary access to the given track’s name (P_NAME).

Returns None if the given track is the master track.

Example

let session = reaper_medium::ReaperSession::default();

let track = session.reaper().get_track(CurrentProject, 0).ok_or("no track")?;
let track_name = unsafe {
    session.reaper().get_set_media_track_info_get_name(
        track,
        |name| name.to_owned()
    )
};
let track_name = match &track_name {
    None => "Master track",
    Some(name) => name.to_str()
};
session.reaper().show_console_msg(format!("Track name is {}", track_name));

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_set_name<'a>(
    &self,
    track: MediaTrack,
    message: impl Into<ReaperStringArg<'a>>
)where
    UsageScope: MainThreadOnly,

Convenience function which sets the track’s name (P_NAME).

Example

let session = reaper_medium::ReaperSession::default();

let track = session.reaper().get_track(CurrentProject, 0).ok_or("no track")?;
unsafe {
    session.reaper().get_set_media_track_info_set_name(track, "Guitar");
}

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_rec_mon(
    &self,
    track: MediaTrack
) -> InputMonitoringModewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s input monitoring mode (I_RECMON).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_solo(
    &self,
    track: MediaTrack
) -> SoloModewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s solo mode (I_SOLO).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_set_solo(
    &self,
    track: MediaTrack,
    mode: SoloMode
)where
    UsageScope: MainThreadOnly,

Convenience function which sets the track’s solo state (I_SOLO).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_set_show_in_mixer(
    &self,
    track: MediaTrack,
    show: bool
)where
    UsageScope: MainThreadOnly,

Convenience function which sets whether the track is shown in the mixer (B_SHOWINMIXER).

Do not use on master track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_set_show_in_tcp(
    &self,
    track: MediaTrack,
    show: bool
)where
    UsageScope: MainThreadOnly,

Convenience function which sets whether the track is shown in the arrange view (B_SHOWINTCP).

Do not use on master track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_pan_mode(
    &self,
    track: MediaTrack
) -> Option<PanMode>where
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s pan mode (I_PANMODE).

Returns None if the track uses the project default.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_pan(
    &self,
    track: MediaTrack
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s pan (D_PAN).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_dual_pan_l(
    &self,
    track: MediaTrack
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s dual-pan position 1 (D_DUALPANL).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_dual_pan_r(
    &self,
    track: MediaTrack
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s dual-pan position 2 (D_DUALPANR).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_width(
    &self,
    track: MediaTrack
) -> ReaperWidthValuewhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s width (D_WIDTH).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_rec_input(
    &self,
    track: MediaTrack
) -> Option<RecordingInput>where
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s recording input (I_RECINPUT).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_track_number(
    &self,
    track: MediaTrack
) -> Option<TrackLocation>where
    UsageScope: MainThreadOnly,

Convenience function which returns the type and location of the given track (IP_TRACKNUMBER).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_guid(&self, track: MediaTrack) -> GUIDwhere
    UsageScope: MainThreadOnly,

Convenience function which returns the given track’s GUID (GUID).

Safety

REAPER can crash if you pass an invalid track.

pub fn is_in_real_time_audio(&self) -> boolwhere
    UsageScope: AnyThread,

Returns whether we are in the real-time audio thread.

Real-time means somewhere between OnAudioBuffer calls, not in some worker or anticipative FX thread.

pub fn audio_is_running(&self) -> boolwhere
    UsageScope: AnyThread,

Returns whether audio is running at all.

pub fn csurf_on_play(&self)where
    UsageScope: MainThreadOnly,

Starts playing.

pub fn csurf_on_stop(&self)where
    UsageScope: MainThreadOnly,

Stops playing.

pub fn csurf_on_pause(&self)where
    UsageScope: MainThreadOnly,

Pauses playing.

pub fn csurf_on_record(&self)where
    UsageScope: MainThreadOnly,

Starts recording.

pub unsafe fn csurf_set_repeat_state(
    &self,
    repeat_state: bool,
    notification_behavior: NotificationBehavior
)where
    UsageScope: MainThreadOnly,

Informs control surfaces that the repeat mode has changed.

Doesn’t actually change the repeat mode.

Safety

REAPER can crash if you pass an invalid control surface.

Example

use reaper_medium::{NotificationBehavior::NotifyAll, ProjectContext::CurrentProject};

let track = session.reaper().get_track(CurrentProject, 0).ok_or("no tracks")?;
unsafe {
    session.reaper().csurf_set_repeat_state(true, NotifyAll);
}

pub fn any_track_solo(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Returns true if any track in the given project is soloed.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn any_track_solo_unchecked(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Like any_track_solo() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn on_play_button_ex(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Directly simulates a play button hit.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn on_play_button_ex_unchecked(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Like on_play_button_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn on_stop_button_ex(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Directly simulates a stop button hit.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn on_stop_button_ex_unchecked(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Like on_stop_button_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn on_pause_button_ex(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Directly simulates a pause button hit.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn on_pause_button_ex_unchecked(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Like on_pause_button_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_play_state_ex(&self, project: ProjectContext) -> PlayStatewhere
    UsageScope: AnyThread,

Queries the current play state.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_play_state_ex_unchecked(
    &self,
    project: ProjectContext
) -> PlayStatewhere
    UsageScope: AnyThread,

Like get_play_state_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_set_repeat_ex_get(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Queries the current repeat state.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_set_repeat_ex_get_unchecked(
    &self,
    project: ProjectContext
) -> boolwhere
    UsageScope: MainThreadOnly,

Like get_set_repeat_ex_get() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_set_repeat_ex_set(&self, project: ProjectContext, repeat: bool)where
    UsageScope: MainThreadOnly,

Sets the repeat state.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_set_repeat_ex_set_unchecked(
    &self,
    project: ProjectContext,
    repeat: bool
)where
    UsageScope: MainThreadOnly,

Like get_set_repeat_ex_set() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn enum_project_markers_3<R>(
    &self,
    project: ProjectContext,
    index: u32,
    use_result: impl FnOnce(Option<EnumProjectMarkers3Result<'_>>) -> R
) -> Rwhere
    UsageScope: MainThreadOnly,

Grants temporary access to the data of the given marker/region.

The given index starts as 0 and counts both markers and regions.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn enum_project_markers_3_unchecked<R>(
    &self,
    project: ProjectContext,
    index: u32,
    use_result: impl FnOnce(Option<EnumProjectMarkers3Result<'_>>) -> R
) -> Rwhere
    UsageScope: MainThreadOnly,

Like enum_project_markers_3() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn pcm_source_create_from_file_ex(
    &self,
    file_name: &Path,
    midi_import_behavior: MidiImportBehavior
) -> Result<OwnedPcmSource, ReaperFunctionError>where
    UsageScope: AnyThread,

Creates a PCM source from the given file name.

Errors

Returns an error if the PCM source could not be created.

Panics

Panics if the given file name is not valid UTF-8.

pub fn pcm_source_create_from_type<'a>(
    &self,
    source_type: impl Into<ReaperStringArg<'a>>
) -> Result<OwnedPcmSource, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Creates a PCM source from a type identifier.

TODO-high Documentation/API … unstable

Use this if you’re going to load its state via LoadState/ProjectStateContext. Valid types include “WAVE”, “MIDI”, or whatever plug-ins define as well.

Errors

Returns an error if the PCM source could not be created.

pub fn go_to_marker(&self, project: ProjectContext, marker: BookmarkRef)where
    UsageScope: MainThreadOnly,

Goes to the given marker.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn go_to_marker_unchecked(
    &self,
    project: ProjectContext,
    marker: BookmarkRef
)where
    UsageScope: MainThreadOnly,

Like go_to_marker() but doesn’t check if project is valid.

Safety

pub fn go_to_region(&self, project: ProjectContext, region: BookmarkRef)where
    UsageScope: MainThreadOnly,

Seeks to the given region after the current one finishes playing (smooth seek).

Panics

Panics if the given project is not valid anymore.

pub unsafe fn go_to_region_unchecked(
    &self,
    project: ProjectContext,
    region: BookmarkRef
)where
    UsageScope: MainThreadOnly,

Like go_to_region() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_time_to_beats(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> TimeMap2TimeToBeatsResultwhere
    UsageScope: AnyThread,

Converts the given time into beats.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_time_to_beats_unchecked(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> TimeMap2TimeToBeatsResultwhere
    UsageScope: AnyThread,

Like time_map_2_time_to_beats() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_get_measure_info(
    &self,
    project: ProjectContext,
    measure_index: i32
) -> TimeMapGetMeasureInfoResultwhere
    UsageScope: AnyThread,

Returns information about the given measure.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_get_measure_info_unchecked(
    &self,
    project: ProjectContext,
    measure_index: i32
) -> TimeMapGetMeasureInfoResultwhere
    UsageScope: AnyThread,

Like time_map_get_measure_info() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_beats_to_time(
    &self,
    project: ProjectContext,
    measure_mode: MeasureMode,
    bpos: PositionInBeats
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Converts the given beat position to time, optionally starting from a specific measure.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_beats_to_time_unchecked(
    &self,
    project: ProjectContext,
    measure_mode: MeasureMode,
    bpos: PositionInBeats
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like time_map_2_beats_to_time() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_qn_to_measures(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> TimeMapQnToMeasuresResultwhere
    UsageScope: AnyThread,

Converts the given quarter-note position to a measure index and returns the measure bounds in quarter notes.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_qn_to_measures_unchecked(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> TimeMapQnToMeasuresResultwhere
    UsageScope: AnyThread,

Like time_map_qn_to_measures() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_qn_to_time(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Converts the given quarter-note position to time.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_qn_to_time_unchecked(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like time_map_2_qn_to_time() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_time_to_qn(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> PositionInQuarterNoteswhere
    UsageScope: AnyThread,

Converts the given time to a quarter-note position.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_time_to_qn_unchecked(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> PositionInQuarterNoteswhere
    UsageScope: AnyThread,

Like time_map_2_time_to_qn() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_qn_to_time_abs(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Converts the given quarter-note position to time.

Quarter notes are counted from the start of the project, regardless of any partial measures.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_qn_to_time_abs_unchecked(
    &self,
    project: ProjectContext,
    qn: PositionInQuarterNotes
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like time_map_2_qn_to_time_abs() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_time_to_qn_abs(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> PositionInQuarterNoteswhere
    UsageScope: AnyThread,

Converts the given time to a quarter-note position.

Quarter notes are counted from the start of the project, regardless of any partial measures.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_time_to_qn_abs_unchecked(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> PositionInQuarterNoteswhere
    UsageScope: AnyThread,

Like time_map_2_time_to_qn_abs() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_set_arrange_view_2_get(
    &self,
    project: ProjectContext,
    screen_x_start: u32,
    screen_x_end: u32
) -> GetSetArrangeView2Resultwhere
    UsageScope: MainThreadOnly,

Gets the arrange view start/end time for the given screen coordinates.

Set both screen_x_start and screen_x_end to 0 to get the full arrange view’s start/end time.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_set_arrange_view_2_get_unchecked(
    &self,
    project: ProjectContext,
    screen_x_start: u32,
    screen_x_end: u32
) -> GetSetArrangeView2Resultwhere
    UsageScope: MainThreadOnly,

Like get_set_arrange_view_2_get() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn time_map_2_get_divided_bpm_at_time(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> Bpmwhere
    UsageScope: AnyThread,

Returns the effective tempo in BPM at the given position (i.e. 2x in /8 signatures).

Panics

Panics if the given project is not valid anymore.

pub unsafe fn time_map_2_get_divided_bpm_at_time_unchecked(
    &self,
    project: ProjectContext,
    tpos: PositionInSeconds
) -> Bpmwhere
    UsageScope: AnyThread,

Like time_map_2_get_divided_bpm_at_time() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_cursor_position_ex(
    &self,
    project: ProjectContext
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Returns the current position of the edit cursor.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_cursor_position_ex_unchecked(
    &self,
    project: ProjectContext
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like get_cursor_position_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_play_position_ex(&self, project: ProjectContext) -> PositionInSecondswhere
    UsageScope: AnyThread,

Returns the latency-compensated actual-what-you-hear position.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_play_position_ex_unchecked(
    &self,
    project: ProjectContext
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like get_play_position_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_play_position_2_ex(
    &self,
    project: ProjectContext
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Returns the position of the next audio block being processed.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_play_position_2_ex_unchecked(
    &self,
    project: ProjectContext
) -> PositionInSecondswhere
    UsageScope: AnyThread,

Like get_play_position_2_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn count_project_markers(
    &self,
    project: ProjectContext
) -> CountProjectMarkersResultwhere
    UsageScope: MainThreadOnly,

Returns the number of markers and regions in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_project_markers_unchecked(
    &self,
    project: ProjectContext
) -> CountProjectMarkersResultwhere
    UsageScope: MainThreadOnly,

Like count_project_markers() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_last_marker_and_cur_region(
    &self,
    project: ProjectContext,
    time: PositionInSeconds
) -> GetLastMarkerAndCurRegionResultwhere
    UsageScope: MainThreadOnly,

Gets the last project marker before the given time and/or the project region that includes the given time.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_last_marker_and_cur_region_unchecked(
    &self,
    project: ProjectContext,
    time: PositionInSeconds
) -> GetLastMarkerAndCurRegionResultwhere
    UsageScope: MainThreadOnly,

Like get_last_marker_and_cur_region() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn main_on_command_ex(
    &self,
    command: CommandId,
    flag: i32,
    project: ProjectContext
)where
    UsageScope: MainThreadOnly,

Performs an action belonging to the main section.

To perform non-native actions (ReaScripts, custom or extension plugin actions) safely, see named_command_lookup().

Panics

Panics if the given project is not valid anymore.

pub unsafe fn main_on_command_ex_unchecked(
    &self,
    command_id: CommandId,
    flag: i32,
    project: ProjectContext
)where
    UsageScope: MainThreadOnly,

Like main_on_command_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn midi_editor_last_focused_on_command(
    &self,
    command_id: CommandId,
    required_view_mode: RequiredViewMode
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sends an action command to the last focused MIDI editor.

Errors

Returns an error if no MIDI editor is open or if the view mode does not match the input.

pub unsafe fn csurf_set_surface_mute(
    &self,
    track: MediaTrack,
    mute: bool,
    notification_behavior: NotificationBehavior
)where
    UsageScope: MainThreadOnly,

Informs control surfaces that the given track’s mute state has changed.

Doesn’t actually change the mute state.

Safety

REAPER can crash if you pass an invalid track or an invalid control surface.

Example

use reaper_medium::{NotificationBehavior::NotifyAll, ProjectContext::CurrentProject};

let track = session.reaper().get_track(CurrentProject, 0).ok_or("no tracks")?;
unsafe {
    session.reaper().csurf_set_surface_mute(track, true, NotifyAll);
}

pub unsafe fn csurf_set_surface_solo(
    &self,
    track: MediaTrack,
    solo: bool,
    notification_behavior: NotificationBehavior
)where
    UsageScope: MainThreadOnly,

Informs control surfaces that the given track’s solo state has changed.

Doesn’t actually change the solo state.

Safety

REAPER can crash if you pass an invalid track or an invalid control surface.

pub fn gen_guid(&self) -> GUIDwhere
    UsageScope: MainThreadOnly,

Generates a random GUID.

pub fn section_from_unique_id<R>(
    &self,
    section_id: SectionId,
    use_section: impl FnOnce(&KbdSectionInfo) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Grants temporary access to the section with the given ID.

Example

use reaper_medium::SectionId;

let action_count =
    session.reaper().section_from_unique_id(SectionId::new(1), |s| s.action_list_cnt());

pub unsafe fn section_from_unique_id_unchecked(
    &self,
    section_id: SectionId
) -> Option<KbdSectionInfo>where
    UsageScope: MainThreadOnly,

Like section_from_unique_id() but returns the section.

Safety

The lifetime of the returned section is unbounded.

pub unsafe fn kbd_on_main_action_ex(
    &self,
    command_id: CommandId,
    value_change: ActionValueChange,
    window: WindowContext,
    project: ProjectContext
) -> i32where
    UsageScope: MainThreadOnly,

Performs an action belonging to the main section.

Unlike main_on_command_ex(), this function also allows to control actions learned with MIDI/OSC.

Safety

REAPER can crash if you pass an invalid project or window.

pub fn prompt_for_action_create(
    &self,
    initial: InitialAction,
    section_id: SectionId
)where
    UsageScope: MainThreadOnly,

Opens an action picker window for prompting the user to select an action.

pub fn prompt_for_action_poll(
    &self,
    section_id: SectionId
) -> PromptForActionResultwhere
    UsageScope: MainThreadOnly,

Polls an action picker session which has been previously created via prompt_for_action_create().

pub fn prompt_for_action_finish(&self, section_id: SectionId)where
    UsageScope: MainThreadOnly,

Finishes an action picker session which has been previously created via prompt_for_action_create().

pub fn get_main_hwnd(&self) -> Hwndwhere
    UsageScope: MainThreadOnly,

Returns the REAPER main window handle.

pub fn midi_editor_get_active(&self) -> Option<Hwnd>where
    UsageScope: MainThreadOnly,

Returns the focused MIDI editor window.

pub fn named_command_lookup<'a>(
    &self,
    command_name: impl Into<ReaperStringArg<'a>>
) -> Option<CommandId>where
    UsageScope: MainThreadOnly,

Looks up the command ID for a named command.

Named commands can be registered by extensions (e.g. _SWS_ABOUT), ReaScripts (e.g. _113088d11ae641c193a2b7ede3041ad5) or custom actions.

pub fn project_config_var_get_offs<'a>(
    &self,
    name: impl Into<ReaperStringArg<'a>>
) -> Option<ProjectConfigVarGetOffsResult>where
    UsageScope: MainThreadOnly,

Returns a project configuration variable descriptor to be used with project_config_var_addr

pub fn project_config_var_addr(
    &self,
    project: ProjectContext,
    index: u32
) -> Option<NonNull<c_void>>where
    UsageScope: MainThreadOnly,

Returns the project configuration object at the given address.

pub unsafe fn project_config_var_addr_unchecked(
    &self,
    project: ProjectContext,
    index: u32
) -> Option<NonNull<c_void>>where
    UsageScope: MainThreadOnly,

Like project_config_var_addr() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_config_var<'a>(
    &self,
    name: impl Into<ReaperStringArg<'a>>
) -> Option<GetConfigVarResult>where
    UsageScope: MainThreadOnly,

Returns the REAPER preference with the given name.

pub fn clear_console(&self)where
    UsageScope: MainThreadOnly,

Clears the ReaScript console.

pub unsafe fn create_track_audio_accessor(
    &self,
    track: MediaTrack
) -> AudioAccessorwhere
    UsageScope: MainThreadOnly,

Safety

REAPER can crash if you pass an invalid track. AudioAccessor has to be destroyed.

pub unsafe fn create_take_audio_accessor(
    &self,
    take: MediaItemTake
) -> AudioAccessorwhere
    UsageScope: MainThreadOnly,

Safety

REAPER can crash if you pass an invalid take. AudioAccessor has to be destroyed.

pub unsafe fn destroy_audio_accessor(&self, accessor: AudioAccessor)where
    UsageScope: MainThreadOnly,

Should be called after using of AudioAccessor.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn audio_accessor_state_changed(
    &self,
    accessor: AudioAccessor
) -> boolwhere
    UsageScope: MainThreadOnly,

Returns true if the underlying samples (track or media item take) have changed

Note

Does not update the audio accessor, so the user can selectively call AudioAccessorValidateState only when needed.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn audio_accessor_update(&self, accessor: AudioAccessor)where
    UsageScope: MainThreadOnly,

Force the accessor to reload its state from the underlying track or media item take.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn audio_accessor_validate_state(
    &self,
    accessor: AudioAccessor
) -> boolwhere
    UsageScope: MainThreadOnly,

Validates the current state of the audio accessor.

Returns true if the state changed.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn get_audio_accessor_end_time(
    &self,
    accessor: AudioAccessor
) -> PositionInSecondswhere
    UsageScope: MainThreadOnly,

Get the end time of the audio that can be returned from this accessor.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn get_audio_accessor_start_time(
    &self,
    accessor: AudioAccessor
) -> PositionInSecondswhere
    UsageScope: MainThreadOnly,

Get the start time of the audio that can be returned from this accessor.

Safety

REAPER can crash if you pass an invalid audio accessor.

pub unsafe fn get_audio_accessor_samples(
    &self,
    accessor: AudioAccessor,
    samplerate: u32,
    channels_amount: u32,
    start_time: PositionInSeconds,
    samples_per_channel: u32,
    sample_buffer: Vec<f64>
) -> Result<bool, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Get a block of samples from the audio accessor.

Samples are extracted immediately pre-FX, and returned interleaved (first sample of first channel, first sample of second channel…).

Returns false if no audio, true if audio

Safety

REAPER can crash if you pass an invalid audio accessor.

pub fn count_tracks(&self, project: ProjectContext) -> u32where
    UsageScope: MainThreadOnly,

Returns the number of tracks in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_tracks_unchecked(&self, project: ProjectContext) -> u32where
    UsageScope: MainThreadOnly,

Like count_tracks() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_project_state_change_count(&self, project: ProjectContext) -> u32where
    UsageScope: MainThreadOnly,

Returns an integer that changes when the project state changes.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_project_state_change_count_unchecked(
    &self,
    project: ProjectContext
) -> u32where
    UsageScope: MainThreadOnly,

Like get_project_state_change_count() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn count_media_items(&self, project: ProjectContext) -> u32where
    UsageScope: MainThreadOnly,

Returns the number of items in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_media_items_unchecked(&self, project: ProjectContext) -> u32where
    UsageScope: MainThreadOnly,

Like count_media_items() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_project_length(&self, project: ProjectContext) -> DurationInSecondswhere
    UsageScope: MainThreadOnly,

Returns the length of the given project.

The length is the maximum of end of media item, markers, end of regions and tempo map.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_project_length_unchecked(
    &self,
    project: ProjectContext
) -> DurationInSecondswhere
    UsageScope: MainThreadOnly,

Like get_project_length() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn set_edit_curs_pos_2(
    &self,
    project: ProjectContext,
    time: PositionInSeconds,
    options: SetEditCurPosOptions
)where
    UsageScope: MainThreadOnly,

Sets the position of the edit cursor and optionally moves the view and/or seeks.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn set_edit_curs_pos_2_unchecked(
    &self,
    project: ProjectContext,
    time: PositionInSeconds,
    options: SetEditCurPosOptions
)where
    UsageScope: MainThreadOnly,

Like set_edit_curs_pos_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_set_loop_time_range_2_get(
    &self,
    project: ProjectContext,
    time_range_type: TimeRangeType
) -> Option<GetLoopTimeRange2Result>where
    UsageScope: MainThreadOnly,

Returns the loop point or time selection time range that’s currently set in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_set_loop_time_range_2_get_unchecked(
    &self,
    project: ProjectContext,
    time_range_type: TimeRangeType
) -> Option<GetLoopTimeRange2Result>where
    UsageScope: MainThreadOnly,

Like get_set_loop_time_range_2_get() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_set_loop_time_range_2_set(
    &self,
    project: ProjectContext,
    time_range_type: TimeRangeType,
    start: PositionInSeconds,
    end: PositionInSeconds,
    auto_seek_behavior: AutoSeekBehavior
)where
    UsageScope: MainThreadOnly,

Sets the loop point or time selection time range for the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_set_loop_time_range_2_set_unchecked(
    &self,
    project: ProjectContext,
    time_range_type: TimeRangeType,
    start: PositionInSeconds,
    end: PositionInSeconds,
    auto_seek_behavior: AutoSeekBehavior
)where
    UsageScope: MainThreadOnly,

Like get_set_loop_time_range_2_set() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn insert_track_at_index(
    &self,
    index: u32,
    defaults_behavior: TrackDefaultsBehavior
)where
    UsageScope: MainThreadOnly,

Creates a new track at the given index.

pub fn midi_reinit(&self)where
    UsageScope: MainThreadOnly,

Resets all MIDI devices.

pub fn get_max_midi_inputs(&self) -> u32where
    UsageScope: AnyThread,

Returns the maximum number of MIDI input devices (usually 63).

pub fn get_max_midi_outputs(&self) -> u32where
    UsageScope: AnyThread,

Returns the maximum number of MIDI output devices (usually 64).

pub fn get_midi_input_name(
    &self,
    device_id: MidiInputDeviceId,
    buffer_size: u32
) -> GetMidiDevNameResultwhere
    UsageScope: MainThreadOnly,

Returns information about the given MIDI input device.

With buffer_size you can tell REAPER how many bytes of the device name you want. If you are not interested in the device name at all, pass 0.

pub fn get_midi_output_name(
    &self,
    device_id: MidiOutputDeviceId,
    buffer_size: u32
) -> GetMidiDevNameResultwhere
    UsageScope: MainThreadOnly,

Returns information about the given MIDI output device.

With buffer_size you can tell REAPER how many bytes of the device name you want. If you are not interested in the device name at all, pass 0.

pub fn reaper_get_pitch_shift_api(
    &self,
    version: i32
) -> Option<OwnedReaperPitchShift>where
    UsageScope: MainThreadOnly,

Returns a new pitch shift API instance.

Version must be raw::REAPER_PITCHSHIFT_API_VER.

pub fn enum_pitch_shift_modes(
    &self,
    mode: PitchShiftMode
) -> Option<EnumPitchShiftModesResult<'static>>where
    UsageScope: MainThreadOnly,

Returns information about the given pitch shift mode.

Start querying modes at 0. Returns None when no more modes possible.

pub fn enum_pitch_shift_sub_modes<R>(
    &self,
    mode: PitchShiftMode,
    sub_mode: PitchShiftSubMode,
    use_name: impl FnOnce(Option<&ReaperStr>) -> R
) -> Rwhere
    UsageScope: MainThreadOnly,

Grants temporary access to the name of the given pitch shift sub mode.

Start querying modes at 0. Returns None when no more sub modes possible.

pub fn resampler_create(&self) -> OwnedReaperResamplewhere
    UsageScope: MainThreadOnly,

Returns a new resample instance.

pub fn resample_enum_modes(
    &self,
    mode: ResampleMode
) -> Option<&'static ReaperStr>where
    UsageScope: MainThreadOnly,

Returns the name of the given resample mode.

Start querying modes at 0. Returns None when no more sub modes possible.

pub unsafe fn track_fx_add_by_name_query<'a>(
    &self,
    track: MediaTrack,
    fx_name: impl Into<ReaperStringArg<'a>>,
    fx_chain_type: TrackFxChainType
) -> Option<u32>where
    UsageScope: MainThreadOnly,

Returns the index of the first FX instance in a track or monitoring FX chain.

The FX name can have a prefix to further specify its type: VST3: | VST2: | VST: | AU: | JS: | DX:

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_param_from_ident(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    ident: ParamId<'_>
) -> Option<u32>where
    UsageScope: MainThreadOnly,

Returns the parameter index corresponding to the given identifier.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_add_by_name_add<'a>(
    &self,
    track: MediaTrack,
    fx_name: impl Into<ReaperStringArg<'a>>,
    fx_chain_type: TrackFxChainType,
    behavior: AddFxBehavior
) -> Result<u32, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Adds an instance of an FX to a track or monitoring FX chain.

See track_fx_add_by_name_query() for possible FX name prefixes.

Errors

Returns an error if the FX couldn’t be added (e.g. if no such FX is installed).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_enabled(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> boolwhere
    UsageScope: MainThreadOnly,

Returns whether the given track FX is enabled.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_offline(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> boolwhere
    UsageScope: MainThreadOnly,

Returns whether the given track FX is offline.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_fx_name(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the name of the given FX.

With buffer_size you can tell REAPER how many bytes of the FX name you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_send_name(
    &self,
    track: MediaTrack,
    send_index: u32,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the name of the given track send or hardware output send.

With buffer_size you can tell REAPER how many bytes of the send name you want.

When choosing the send index, keep in mind that the hardware output sends (if any) come first.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the track send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_receive_name(
    &self,
    track: MediaTrack,
    receive_index: u32,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the name of the given track receive.

With buffer_size you can tell REAPER how many bytes of the receive name you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the track send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_instrument(&self, track: MediaTrack) -> Option<u32>where
    UsageScope: MainThreadOnly,

Returns the index of the first track FX that is a virtual instrument.

Doesn’t look in the input FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_enabled(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    enabled: bool
)where
    UsageScope: MainThreadOnly,

Enables or disables a track FX.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_offline(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    offline: bool
)where
    UsageScope: MainThreadOnly,

Sets the given track FX offline or online.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_num_params(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> u32where
    UsageScope: MainThreadOnly,

Returns the number of parameters of given track FX.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_input_output_latency(&self) -> GetInputOutputLatencyResultwhere
    UsageScope: AnyThread,

Returns the audio device input/output latency in samples.

pub fn get_current_project_in_load_save(&self) -> Option<ReaProject>where
    UsageScope: MainThreadOnly,

Returns the current project if it’s just being loaded or saved.

This is usually only used from project_config_extension_t.

pub unsafe fn track_fx_get_param_name(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the name of the given track FX parameter.

With buffer_size you can tell REAPER how many bytes of the parameter name you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_formatted_param_value(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the current value of the given track FX parameter formatted as string.

With buffer_size you can tell REAPER how many bytes of the parameter value string you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_format_param_value_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    param_value: ReaperNormalizedFxParamValue,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the given value formatted as string according to the given track FX parameter.

With buffer_size you can tell REAPER how many bytes of the parameter value string you want.

This only works with FX that supports Cockos VST extensions.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn’t exist. Also errors if the FX doesn’t support formatting arbitrary parameter values and the given value is not equal to the current one. If the given value is equal to the current one, it’s just like calling track_fx_get_formatted_param_value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_param_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    param_value: ReaperNormalizedFxParamValue
) -> Result<(), ReaperFunctionError>where
    UsageScope: AnyThread,

Sets the value of the given track FX parameter.

Errors

Returns an error if the FX or parameter doesn’t exist.

Safety

• REAPER can crash if you pass an invalid track.
• Calling this from any other thread than the main thread causes undefined behavior!
• However, there’s one exception: Calling it in a real-time thread directly “from the track” which is currently processing is okay, and only for REAPER >= v6.52+dev0323. Previous REAPER versions will send control surface change notifications, in the wrong thread. Newer versions don’t send any notifications when this function is called in real-time.

pub unsafe fn track_fx_end_param_edit(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> Result<(), ReaperFunctionError>where
    UsageScope: AnyThread,

Notifies REAPER that we are done changing parameter values

This is important for automation mode Touch.

Errors

Returns an error if the FX or parameter doesn’t exist.

Safety

• REAPER can crash if you pass an invalid track.
• Calling this from any other thread than the main thread causes undefined behavior!
• However, there’s one exception: Calling it in a real-time thread directly “from the track” which is currently processing is okay, and only for REAPER >= v6.52+dev0323. Previous REAPER versions will send control surface change notifications, in the wrong thread. Newer versions don’t send any notifications when this function is called in real-time.

pub fn get_focused_fx(&self) -> Option<GetFocusedFxResult>where
    UsageScope: MainThreadOnly,

👎Deprecated: use get_focused_fx_2 instead

Returns information about the (last) focused FX window.

Returns Some if an FX window has focus or was the last focused one and is still open.

Returns None otherwise.

pub fn get_focused_fx_2(&self) -> Option<GetFocusedFx2Result>where
    UsageScope: MainThreadOnly,

Returns information about the focused FX window.

Returns Some if an FX window has focus or was the last focused one and is still open. The wrapped value contains additional information about whether the window is still focused.

Returns None otherwise.

pub fn get_last_touched_fx(&self) -> Option<GetLastTouchedFxResult>where
    UsageScope: MainThreadOnly,

Returns information about the last touched FX parameter.

Returns Some if an FX parameter has been touched already and that FX is still existing. Returns None otherwise.

pub unsafe fn track_fx_copy_to_track(
    &self,
    source: (MediaTrack, TrackFxLocation),
    destination: (MediaTrack, TrackFxLocation),
    transfer_behavior: TransferBehavior
)where
    UsageScope: MainThreadOnly,

Copies, moves or reorders FX.

Reorders if source and destination track are the same.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_delete(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Removes the given FX from the track FX chain.

Errors

Returns an error if the FX doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_parameter_step_sizes(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> Option<GetParameterStepSizesResult>where
    UsageScope: AnyThread,

Returns information about the given FX parameter’s step sizes.

Returns None if the FX parameter doesn’t report step sizes or if the FX or parameter doesn’t exist (there’s no way to distinguish with just this function).

Safety

• REAPER can crash if you pass an invalid track.
• Calling this from any other thread than the main thread causes undefined behavior!
• However, there’s one exception: Calling it in a real-time thread directly “from the track” which is currently processing should be okay.

pub unsafe fn track_fx_get_param_ex(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> GetParamExResultwhere
    UsageScope: AnyThread,

Returns the current value and min/mid/max values of the given track FX.

Safety

• REAPER can crash if you pass an invalid track.
• Calling this from any other thread than the main thread causes undefined behavior!
• However, there’s one exception: Calling it in a real-time thread directly “from the track” which is currently processing should be okay.

pub unsafe fn track_fx_get_named_config_parm<'a>(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_name: impl Into<ReaperStringArg<'a>>,
    buffer_size: u32
) -> Result<Vec<u8>, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Gets a plug-in specific named configuration value.

With buffer_size you can tell REAPER and the FX how many bytes of the value you want.

Named parameters are a vendor-specific VST extension from Cockos (see http://reaper.fm/sdk/vst/vst_ext.php).

Errors

Returns an error if the given FX doesn’t have this named parameter or doesn’t support named parameters.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_named_config_parm_as_string<'a>(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_name: impl Into<ReaperStringArg<'a>>,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Like track_fx_get_named_config_parm but interpreting the result as a string.

Errors

Returns an error if the given FX doesn’t have this named parameter, doesn’t support named parameters or if the returned data doesn’t resemble a proper string.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_named_config_parm<'a>(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_name: impl Into<ReaperStringArg<'a>>,
    buffer: &[u8]
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets a plug-in specific named configuration value.

Named parameters are a vendor-specific VST extension from Cockos (see http://reaper.fm/sdk/vst/vst_ext.php).

Errors

Returns an error if the given FX doesn’t have this named parameter or doesn’t support named parameters.

Safety

REAPER can crash if you pass an invalid track.

pub fn undo_begin_block_2(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Starts a new undo block.

Panics

Panics if the given project is not valid anymore.

Example

use reaper_medium::{ProjectContext::CurrentProject, UndoScope::Scoped, ProjectPart::*};

session.reaper().undo_begin_block_2(CurrentProject);
// ... modify something ...
session.reaper().undo_end_block_2(CurrentProject, "Modify something", Scoped(Items | Fx));

pub unsafe fn undo_begin_block_2_unchecked(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Like undo_begin_block_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_end_block_2<'a>(
    &self,
    project: ProjectContext,
    description: impl Into<ReaperStringArg<'a>>,
    scope: UndoScope
)where
    UsageScope: MainThreadOnly,

Ends the current undo block.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_end_block_2_unchecked<'a>(
    &self,
    project: ProjectContext,
    description: impl Into<ReaperStringArg<'a>>,
    scope: UndoScope
)where
    UsageScope: MainThreadOnly,

Like undo_end_block_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_can_undo_2<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Grants temporary access to the the description of the last undoable operation, if any.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_can_undo_2_unchecked<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Like undo_can_undo_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_can_redo_2<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Grants temporary access to the description of the next redoable operation, if any.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_can_redo_2_unchecked<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Like undo_can_redo_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_do_undo_2(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Makes the last undoable operation undone.

Returns false if there was nothing to be undone.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_do_undo_2_unchecked(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Like undo_do_undo_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_do_redo_2(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Executes the next redoable action.

Returns false if there was nothing to be redone.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_do_redo_2_unchecked(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Like undo_do_redo_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn mark_project_dirty(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Marks the given project as dirty.

Dirty means the project needs to be saved. Only makes a difference if “Maximum undo memory” is not 0 in REAPER’s preferences (0 disables undo/prompt to save).

Panics

Panics if the given project is not valid anymore.

pub unsafe fn mark_project_dirty_unchecked(&self, project: ProjectContext)where
    UsageScope: MainThreadOnly,

Like mark_project_dirty() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn is_project_dirty(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Returns whether the given project is dirty.

Always returns false if “Maximum undo memory” is 0 in REAPER’s preferences.

Also see mark_project_dirty()

Panics

Panics if the given project is not valid anymore.

pub unsafe fn is_project_dirty_unchecked(&self, project: ProjectContext) -> boolwhere
    UsageScope: MainThreadOnly,

Like is_project_dirty() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn track_list_update_all_external_surfaces(&self)where
    UsageScope: MainThreadOnly,

Notifies all control surfaces that something in the track list has changed.

Behavior not confirmed.

pub fn get_app_version(&self) -> ReaperVersion<'static>where
    UsageScope: AnyThread,

Returns the version of the REAPER application in which this plug-in is currently running.

pub unsafe fn get_track_automation_mode(
    &self,
    track: MediaTrack
) -> AutomationModewhere
    UsageScope: MainThreadOnly,

Returns the track automation mode, regardless of the global override.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_color(
    &self,
    track: MediaTrack
) -> Option<NativeColorResult>where
    UsageScope: MainThreadOnly,

Returns the custom color of the given track.

Safety

REAPER can crash if you pass an invalid track.

pub fn color_from_native(&self, color: NativeColor) -> RgbColorwhere
    UsageScope: MainThreadOnly,

Extracts an RGB color from the given OS-dependent color.

pub fn gr_select_color(&self, window: WindowContext) -> Option<NativeColor>where
    UsageScope: MainThreadOnly,

Runs the system color chooser dialog.

Returns None if the user cancels the dialog.

pub unsafe fn set_track_automation_mode(
    &self,
    track: MediaTrack,
    automation_mode: AutomationMode
)where
    UsageScope: MainThreadOnly,

Sets the track automation mode.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_global_automation_override(
    &self
) -> Option<GlobalAutomationModeOverride>where
    UsageScope: MainThreadOnly,

Returns the global track automation override, if any.

pub fn set_global_automation_override(
    &self,
    mode_override: Option<GlobalAutomationModeOverride>
)where
    UsageScope: MainThreadOnly,

Sets the global track automation override.

pub unsafe fn get_track_envelope_by_chunk_name(
    &self,
    track: MediaTrack,
    chunk_name: EnvChunkName<'_>
) -> Option<TrackEnvelope>where
    UsageScope: MainThreadOnly,

Returns the track envelope for the given track and configuration chunk name.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_envelope_by_name<'a>(
    &self,
    track: MediaTrack,
    env_name: impl Into<ReaperStringArg<'a>>
) -> Option<TrackEnvelope>where
    UsageScope: MainThreadOnly,

Returns the track envelope for the given track and envelope display name.

For getting common envelopes (like volume or pan) using get_track_envelope_by_chunk_name() is better because it provides more type safety.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_get_peak_info(
    &self,
    track: MediaTrack,
    channel: u32
) -> ReaperVolumeValuewhere
    UsageScope: MainThreadOnly,

Returns the current peak volume for the given track channel.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_media_track_info_value(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey<'_>
) -> f64where
    UsageScope: MainThreadOnly,

Gets a track attribute as numerical value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_send_info_value(
    &self,
    track: MediaTrack,
    category: TrackSendCategory,
    send_index: u32,
    attribute_key: TrackSendAttributeKey<'_>
) -> f64where
    UsageScope: MainThreadOnly,

Gets a track track send, hardware output send or track receive attribute as numerical value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn count_track_media_items(&self, track: MediaTrack) -> u32where
    UsageScope: MainThreadOnly,

Counts the number of items in the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn count_tcp_fx_parms(
    &self,
    project: ProjectContext,
    track: MediaTrack
) -> u32where
    UsageScope: MainThreadOnly,

Counts the number of FX parameter knobs displayed on the track control panel.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_tcp_fx_parm(
    &self,
    project: ProjectContext,
    track: MediaTrack,
    index: u32
) -> Result<GetTcpFxParmResult, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns information about a specific FX parameter knob displayed on the track control panel.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_media_item(
    &self,
    track: MediaTrack,
    item_idx: u32
) -> Option<MediaItem>where
    UsageScope: MainThreadOnly,

Returns the media item on the given track at the given index.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_count(&self, track: MediaTrack) -> u32where
    UsageScope: MainThreadOnly,

Gets the number of FX instances on the given track’s normal FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_rec_count(&self, track: MediaTrack) -> u32where
    UsageScope: MainThreadOnly,

Gets the number of FX instances on the given track’s input FX chain.

On the master track, this refers to the monitoring FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_fx_guid(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Result<GUID, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the GUID of the given track FX.

Errors

Returns an error if the FX doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_param_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> ReaperNormalizedFxParamValuewhere
    UsageScope: AnyThread,

Returns the current value of the given track FX in REAPER-normalized form.

If the returned value is lower than zero, it can mean two things. Either there was an error, e.g. the FX or parameter doesn’t exist, or the parameter can take exotic values. There’s no way to distinguish between both cases. See ReaperNormalizedFxParamValue for details.

Safety

• REAPER can crash if you pass an invalid track.
• Calling this from any other thread than the main thread causes undefined behavior!
• However, there’s one exception: Calling it in a real-time thread directly “from the track” which is currently processing should be okay.

pub fn get_master_track(&self, project: ProjectContext) -> MediaTrackwhere
    UsageScope: MainThreadOnly,

Returns the master track of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_master_track_unchecked(
    &self,
    project: ProjectContext
) -> MediaTrackwhere
    UsageScope: MainThreadOnly,

Like get_master_track() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn guid_to_string(&self, guid: &GUID) -> ReaperStringwhere
    UsageScope: AnyThread,

Converts the given GUID to a string (including braces).

pub fn kbd_format_key_name(&self, accel: Accel) -> ReaperStringwhere
    UsageScope: AnyThread,

Converts the given accelerator key to a human-readable name.

pub fn get_project_path_ex(
    &self,
    project: ProjectContext,
    buffer_size: u32
) -> PathBufwhere
    UsageScope: MainThreadOnly,

Returns the project recording path.

With buffer_size you can tell REAPER how many bytes of the resulting path you want.

Panics

Panics if the given buffer size is 0.

pub unsafe fn get_project_path_ex_unchecked(
    &self,
    project: ProjectContext,
    buffer_size: u32
) -> PathBufwhere
    UsageScope: MainThreadOnly,

Like get_project_path_ex() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn master_get_tempo(&self) -> Bpmwhere
    UsageScope: MainThreadOnly,

Returns the master tempo of the current project.

pub fn set_current_bpm(
    &self,
    project: ProjectContext,
    tempo: Bpm,
    undo_behavior: UndoBehavior
)where
    UsageScope: MainThreadOnly,

Sets the current tempo of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn set_current_bpm_unchecked(
    &self,
    project: ProjectContext,
    tempo: Bpm,
    undo_behavior: UndoBehavior
)where
    UsageScope: MainThreadOnly,

Like set_current_bpm() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn master_normalize_play_rate_normalize(
    &self,
    value: PlaybackSpeedFactor
) -> NormalizedPlayRatewhere
    UsageScope: MainThreadOnly,

Converts the given playback speed factor to a normalized play rate.

pub fn master_normalize_play_rate_denormalize(
    &self,
    value: NormalizedPlayRate
) -> PlaybackSpeedFactorwhere
    UsageScope: MainThreadOnly,

Converts the given normalized play rate to a playback speed factor.

pub fn master_get_play_rate(
    &self,
    project: ProjectContext
) -> PlaybackSpeedFactorwhere
    UsageScope: MainThreadOnly,

Returns the master play rate of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn master_get_play_rate_unchecked(
    &self,
    project: ProjectContext
) -> PlaybackSpeedFactorwhere
    UsageScope: MainThreadOnly,

Like master_get_play_rate() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn csurf_on_play_rate_change(&self, play_rate: PlaybackSpeedFactor)

Sets the master play rate of the current project.

pub fn show_message_box<'a>(
    &self,
    message: impl Into<ReaperStringArg<'a>>,
    title: impl Into<ReaperStringArg<'a>>,
    type: MessageBoxType
) -> MessageBoxResultwhere
    UsageScope: MainThreadOnly,

Shows a message box to the user.

Blocks the main thread.

pub fn help_set<'a>(
    &self,
    message: impl Into<ReaperStringArg<'a>>,
    mode: HelpMode
)where
    UsageScope: MainThreadOnly,

Displays a text close to the transport bar.

pub fn string_to_guid<'a>(
    &self,
    guid_string: impl Into<ReaperStringArg<'a>>
) -> Result<GUID, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Parses the given string as GUID.

Errors

Returns an error if the given string is not a valid GUID string.

pub unsafe fn csurf_on_input_monitoring_change_ex(
    &self,
    track: MediaTrack,
    mode: InputMonitoringMode,
    gang_behavior: GangBehavior
) -> InputMonitoringModewhere
    UsageScope: MainThreadOnly,

Sets the input monitoring mode of the given track.

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_input_monitor(
    &self,
    track: MediaTrack,
    mode: InputMonitoringMode,
    flags: BitFlags<SetTrackUiFlags>
) -> InputMonitoringModewhere
    UsageScope: MainThreadOnly,

Sets the input monitoring mode of the given track.

Has fewer side effects than Reaper::csurf_on_input_monitoring_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_mixer_scroll(&self, track: MediaTrack) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Scrolls the mixer so that the given track is the leftmost visible track.

Returns the leftmost visible track after scrolling, which may be different from the given track if there are not enough tracks to its right. Not exactly sure what it’s supposed to mean if this returns None, but it happens at times.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn add_media_item_to_track(
    &self,
    track: MediaTrack
) -> Result<MediaItem, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Creates a new media item.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn delete_track_media_item(
    &self,
    track: MediaTrack,
    item: MediaItem
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Deletes the given media item.

Errors

Returns an error if not successful.

Safety

REAPER can crash if you pass an invalid track or item.

pub unsafe fn add_take_to_media_item(
    &self,
    item: MediaItem
) -> Result<MediaItemTake, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Creates a new take in an item.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn set_media_item_position(
    &self,
    item: MediaItem,
    pos: PositionInSeconds,
    refresh_behavior: UiRefreshBehavior
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets the position of the given item.

Errors

Returns an error if not successful.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn set_media_item_length(
    &self,
    item: MediaItem,
    length: DurationInSeconds,
    refresh_behavior: UiRefreshBehavior
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets the length of the given item.

Errors

Returns an error if not successful.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn set_media_item_selected(&self, item: MediaItem, selected: bool)where
    UsageScope: MainThreadOnly,

Selects or unselects the given media item.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn set_media_track_info_value(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey<'_>,
    new_value: f64
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets a track attribute as numerical value.

Errors

Returns an error if an invalid (e.g. non-numerical) track attribute key is passed.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_send_info_value(
    &self,
    track: MediaTrack,
    category: TrackSendCategory,
    send_index: u32,
    attribute_key: TrackSendAttributeKey<'_>,
    new_value: f64
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets a track track send, hardware output send or track receive attribute as numerical value.

Errors

Returns an error if an invalid (e.g. non-numerical) attribute key is passed.

Safety

REAPER can crash if you pass an invalid track.

pub fn stuff_midi_message(
    &self,
    target: StuffMidiMessageTarget,
    message: impl ShortMessage
)where
    UsageScope: MainThreadOnly,

Stuffs a 3-byte MIDI message into a queue or send it to an external MIDI hardware.

Example

use helgoboss_midi::test_util::note_on;
use reaper_medium::StuffMidiMessageTarget::VirtualMidiKeyboardQueue;

session.reaper().stuff_midi_message(VirtualMidiKeyboardQueue, note_on(0, 64, 100));

pub fn db2slider(&self, value: Db) -> VolumeSliderValuewhere
    UsageScope: AnyThread,

Converts a decibel value into a volume slider value.

pub fn slider2db(&self, value: VolumeSliderValue) -> Dbwhere
    UsageScope: AnyThread,

Converts a volume slider value into a decibel value.

pub unsafe fn get_track_ui_vol_pan(
    &self,
    track: MediaTrack
) -> Result<VolumeAndPan, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the given track’s volume and incomplete pan. Also returns the correct value during the process of writing an automation envelope.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_ui_mute(
    &self,
    track: MediaTrack
) -> Result<bool, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the given track’s mute state. Also returns the correct value during the process of writing an automation envelope.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_ui_pan(
    &self,
    track: MediaTrack
) -> Result<GetTrackUiPanResult, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the given track’s complete pan. Also returns the correct value during the process of writing an automation envelope.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_set_surface_volume(
    &self,
    track: MediaTrack,
    volume: ReaperVolumeValue,
    notification_behavior: NotificationBehavior
)where
    UsageScope: MainThreadOnly,

Informs control surfaces that the given track’s volume has changed.

Doesn’t actually change the volume.

Safety

REAPER can crash if you pass an invalid track or an invalid control surface.

pub unsafe fn csurf_on_volume_change_ex(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperVolumeValue>,
    gang_behavior: GangBehavior
) -> ReaperVolumeValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s volume, also supports relative changes and gang.

Returns the new value. I think this only deviates if 0.0 is sent. Then it returns a slightly higher value - the one which actually corresponds to -150 dB.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_volume(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperVolumeValue>,
    progress: Progress,
    flags: BitFlags<SetTrackUiFlags>
) -> ReaperVolumeValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s volume, also supports relative changes and gang.

Returns the new value. I think this only deviates if 0.0 is sent. Then it returns a slightly higher value - the one which actually corresponds to -150 dB.

Has fewer side effects than Reaper::csurf_on_volume_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_set_surface_pan(
    &self,
    track: MediaTrack,
    pan: ReaperPanValue,
    notification_behavior: NotificationBehavior
)where
    UsageScope: MainThreadOnly,

Informs control surfaces that the given track’s pan has been changed.

Doesn’t actually change the pan.

Safety

REAPER can crash if you pass an invalid track or an invalid control surface.

pub unsafe fn csurf_on_pan_change_ex(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperPanValue>,
    gang_behavior: GangBehavior
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s pan. Also supports relative changes and gang.

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_pan(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperPanValue>,
    progress: Progress,
    flags: BitFlags<SetTrackUiFlags>
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s pan. Also supports relative changes and gang.

Returns the new value.

Has fewer side effects than Reaper::csurf_on_pan_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_polarity(
    &self,
    track: MediaTrack,
    value: TrackPolarityOperation,
    flags: BitFlags<SetTrackUiFlags>
) -> TrackPolaritywhere
    UsageScope: MainThreadOnly,

Sets the given track’s polarity (phase).

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_width_change_ex(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperWidthValue>,
    gang_behavior: GangBehavior
) -> ReaperWidthValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s width. Also supports relative changes and gang.

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_width(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperWidthValue>,
    progress: Progress,
    flags: BitFlags<SetTrackUiFlags>
) -> ReaperWidthValuewhere
    UsageScope: MainThreadOnly,

Sets the given track’s width. Also supports relative changes and gang.

Returns the new value.

Has fewer side effects than Reaper::csurf_on_width_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub fn count_selected_tracks_2(
    &self,
    project: ProjectContext,
    master_track_behavior: MasterTrackBehavior
) -> u32where
    UsageScope: MainThreadOnly,

Counts the number of selected tracks in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_selected_tracks_2_unchecked(
    &self,
    project: ProjectContext,
    master_track_behavior: MasterTrackBehavior
) -> u32where
    UsageScope: MainThreadOnly,

Like count_selected_tracks_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub unsafe fn set_track_selected(&self, track: MediaTrack, is_selected: bool)where
    UsageScope: MainThreadOnly,

Selects or deselects the given track.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_selected_track_2(
    &self,
    project: ProjectContext,
    selected_track_index: u32,
    master_track_behavior: MasterTrackBehavior
) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Returns a selected track from the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_selected_track_2_unchecked(
    &self,
    project: ProjectContext,
    selected_track_index: u32,
    master_track_behavior: MasterTrackBehavior
) -> Option<MediaTrack>where
    UsageScope: MainThreadOnly,

Like get_selected_track_2() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn get_selected_media_item(
    &self,
    project: ProjectContext,
    selected_item_index: u32
) -> Option<MediaItem>where
    UsageScope: MainThreadOnly,

Returns a selected item from the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_selected_media_item_unchecked(
    &self,
    project: ProjectContext,
    selected_item_index: u32
) -> Option<MediaItem>where
    UsageScope: MainThreadOnly,

Like get_selected_media_item() but doesn’t check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub unsafe fn get_media_item_take_source(
    &self,
    take: MediaItemTake
) -> Option<PcmSource>where
    UsageScope: MainThreadOnly,

Returns the media source of the given media item take.

Safety

REAPER can crash if you pass an invalid take.

pub unsafe fn get_item_project_context(
    &self,
    item: MediaItem
) -> Option<ReaProject>where
    UsageScope: MainThreadOnly,

Unstable!!!

Returns the project which contains this item.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn get_active_take(&self, item: MediaItem) -> Option<MediaItemTake>where
    UsageScope: MainThreadOnly,

Returns the active take in this item.

Safety

REAPER can crash if you pass an invalid item.

pub unsafe fn midi_editor_get_take(
    &self,
    midi_editor: Hwnd
) -> Result<MediaItemTake, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the take that is currently being edited in the given MIDI editor.

Safety

REAPER can crash if you pass an invalid window.

pub unsafe fn set_only_track_selected(&self, track: Option<MediaTrack>)where
    UsageScope: MainThreadOnly,

Selects exactly one track and deselects all others.

If None is passed, deselects all tracks.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn delete_track(&self, track: MediaTrack)where
    UsageScope: MainThreadOnly,

Deletes the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_num_sends(
    &self,
    track: MediaTrack,
    category: TrackSendCategory
) -> u32where
    UsageScope: MainThreadOnly,

Returns the number of track sends, hardware output sends or track receives of the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_track_send_info(
    &self,
    track: MediaTrack,
    category: TrackSendCategory,
    send_index: u32,
    attribute_key: TrackSendAttributeKey<'_>,
    new_value: *mut c_void
) -> *mut c_voidwhere
    UsageScope: MainThreadOnly,

Gets or sets an attribute of the given track send, hardware output send or track receive.

Returns the current value if new_value is null_mut().

Safety

REAPER can crash if you pass an invalid track or invalid new value.

pub unsafe fn get_track_send_info_srctrack(
    &self,
    track: MediaTrack,
    direction: TrackSendDirection,
    send_index: u32
) -> Result<MediaTrack, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Convenience function which returns the destination track (P_SRCTRACK) of the given track send or track receive.

The given index starts at zero for both track sends and receives.

Errors

Returns an error e.g. if the send or receive doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_send_info_desttrack(
    &self,
    track: MediaTrack,
    direction: TrackSendDirection,
    send_index: u32
) -> Result<MediaTrack, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Convenience function which returns the destination track (P_DESTTRACK) of the given track send or track receive.

The given index starts at zero for both track sends and receives.

Errors

Returns an error e.g. if the send or receive doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_state_chunk(
    &self,
    track: MediaTrack,
    buffer_size: u32,
    cache_hint: ChunkCacheHint
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the RPPXML state of the given track.

With buffer_size you can tell REAPER how many bytes of the chunk you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub fn get_user_inputs<'a>(
    &self,
    title: impl Into<ReaperStringArg<'a>>,
    num_inputs: u32,
    captions_csv: impl Into<ReaperStringArg<'a>>,
    initial_csv: impl Into<ReaperStringArg<'a>>,
    buffer_size: u32
) -> Option<ReaperString>where
    UsageScope: MainThreadOnly,

Prompts the user for string values.

If a caption begins with *, for example *password, the edit field will not display the input text. The maximum number of fields is 16. Values are returned as a comma-separated string.

You can supply special extra information via additional caption fields:

• extrawidth=XXX to increase text field width
• separator=X to use a different separator for returned fields

With buffer_size you can tell REAPER how many bytes of the resulting CSV you want.

Panics

Panics if the given buffer size is 0.

pub unsafe fn create_track_send(
    &self,
    track: MediaTrack,
    target: SendTarget
) -> Result<u32, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Creates a track send, track receive or hardware output send for the given track.

Returns the index of the created track send (starting from 0) or of the created hardware output send (also starting from 0).

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

Example

use reaper_medium::{ProjectContext::CurrentProject, SendTarget::HardwareOutput};

let src_track = session.reaper().get_track(CurrentProject, 0).ok_or("no tracks")?;
let send_index = unsafe {
    session.reaper().create_track_send(src_track, HardwareOutput)?;
};

pub unsafe fn remove_track_send(
    &self,
    track: MediaTrack,
    category: TrackSendCategory,
    send_index: u32
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Removes a track send, track receive or hardware output send from the given track.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_rec_arm_change_ex(
    &self,
    track: MediaTrack,
    mode: RecordArmMode,
    gang_behavior: GangBehavior
) -> boolwhere
    UsageScope: MainThreadOnly,

Arms or disarms the given track for recording.

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_rec_arm(
    &self,
    track: MediaTrack,
    value: TrackRecArmOperation,
    flags: BitFlags<SetTrackUiFlags>
) -> RecordArmModewhere
    UsageScope: MainThreadOnly,

Arms or disarms the given track for recording.

Returns the new value.

Has fewer side effects than Reaper::csurf_on_rec_arm_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_mute_change_ex(
    &self,
    track: MediaTrack,
    mute: bool,
    gang_behavior: GangBehavior
) -> boolwhere
    UsageScope: MainThreadOnly,

Mutes or unmutes the given track.

Seems to return the mute state that has been set.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_mute(
    &self,
    track: MediaTrack,
    mute: TrackMuteOperation,
    flags: BitFlags<SetTrackUiFlags>
) -> TrackMuteStatewhere
    UsageScope: MainThreadOnly,

Mutes or unmutes the given track.

Returns the new value.

Has fewer side effects than Reaper::csurf_on_mute_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_solo_change_ex(
    &self,
    track: MediaTrack,
    solo: bool,
    gang_behavior: GangBehavior
) -> boolwhere
    UsageScope: MainThreadOnly,

Soloes or unsoloes the given track.

Seems to return the solo state that has been set.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_ui_solo(
    &self,
    track: MediaTrack,
    value: TrackSoloOperation,
    flags: BitFlags<SetTrackUiFlags>
) -> i32where
    UsageScope: MainThreadOnly,

Soloes or unsoloes the given track.

TODO-high The return value will change in future. Not clear yet how to interpret it.

Returns the new value.

Has fewer side effects than Reaper::csurf_on_solo_change_ex and allows more fine-grained control of track grouping behavior.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_state_chunk<'a>(
    &self,
    track: MediaTrack,
    chunk: impl Into<ReaperStringArg<'a>>,
    cache_hint: ChunkCacheHint
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets the RPPXML state of the given track.

Errors

Returns an error if not successful (for example if the given chunk is not accepted).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_show(
    &self,
    track: MediaTrack,
    instruction: FxShowInstruction
)where
    UsageScope: MainThreadOnly,

Shows or hides an FX user interface.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_floating_window(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Option<Hwnd>where
    UsageScope: MainThreadOnly,

Returns the floating window handle of the given FX, if there is any.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_open(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> boolwhere
    UsageScope: MainThreadOnly,

Returns whether the user interface of the given FX is open.

Open means either visible in the FX chain window or visible in a floating window.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_chain_visible(
    &self,
    track: MediaTrack
) -> FxChainVisibilitywhere
    UsageScope: MainThreadOnly,

Returns the visibility state of the given track’s normal FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_master_track_visibility(&self) -> BitFlags<TrackArea>where
    UsageScope: MainThreadOnly,

Returns the visibility state of the master track.

Safety

REAPER can crash if you pass an invalid track.

pub fn set_master_track_visibility(
    &self,
    areas: BitFlags<TrackArea>
) -> BitFlags<TrackArea>where
    UsageScope: MainThreadOnly,

Sets the visibility state of the master track and returns the previous one.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_rec_chain_visible(
    &self,
    track: MediaTrack
) -> FxChainVisibilitywhere
    UsageScope: MainThreadOnly,

Returns the visibility state of the given track’s input FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_send_volume_change(
    &self,
    track: MediaTrack,
    send_index: u32,
    value_change: ValueChange<ReaperVolumeValue>
) -> ReaperVolumeValuewhere
    UsageScope: MainThreadOnly,

Sets the volume of the given track send or hardware output send.

When choosing the send index, keep in mind that the hardware output sends (if any) come first.

Returns the new value. If the send doesn’t exist, returns 0.0 (which can also be a valid value that has been set, so that’s not very useful).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_send_pan_change(
    &self,
    track: MediaTrack,
    send_index: u32,
    value_change: ValueChange<ReaperPanValue>
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Sets the pan of the given track send or hardware output send.

When choosing the send index, keep in mind that the hardware output sends (if any) come first.

Returns the new value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn kbd_get_text_from_cmd<R>(
    &self,
    command_id: CommandId,
    section: SectionContext<'_>,
    use_action_name: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Grants temporary access to the name of the action registered under the given command ID within the specified section.

Returns None if the action doesn’t exist.

Safety

REAPER can crash if you pass an invalid section.

pub fn get_resource_path<R>(
    &self,
    use_resource_path: impl FnOnce(&Path) -> R
) -> Rwhere
    UsageScope: MainThreadOnly,

Grants temporary access to the REAPER resource path.

This is the path to the directory where INI files are stored and other things in subdirectories.

pub fn get_take_name<R>(
    &self,
    take: MediaItemTake,
    use_name: impl FnOnce(Result<&ReaperStr, ReaperFunctionError>) -> R
) -> Rwhere
    UsageScope: MainThreadOnly,

Grants temporary access to the name of the given take.

Error

Returns an error if the take is not valid.

pub unsafe fn get_toggle_command_state_2(
    &self,
    section: SectionContext<'_>,
    command_id: CommandId
) -> Option<bool>where
    UsageScope: MainThreadOnly,

Returns the current on/off state of a toggleable action.

Returns None if the action doesn’t support on/off states (or if the action doesn’t exist).

Safety

REAPER can crash if you pass an invalid section.

pub fn get_toggle_command_state_ex(
    &self,
    section_id: SectionId,
    command_id: CommandId
) -> Option<bool>where
    UsageScope: MainThreadOnly,

Returns the current on/off state of a toggleable action, taking the section ID.

Returns None if the action doesn’t support on/off states (or if the action doesn’t exist).

pub fn reverse_named_command_lookup<R>(
    &self,
    command_id: CommandId,
    use_command_name: impl FnOnce(&ReaperStr) -> R
) -> Option<R>where
    UsageScope: MainThreadOnly,

Grants temporary access to the name of the command registered under the given command ID.

The string will not start with _ (e.g. it will return SWS_ABOUT).

Returns None if the given command ID is a built-in action or if there’s no such ID.

pub unsafe fn get_track_send_ui_vol_pan(
    &self,
    track: MediaTrack,
    send_index: u32
) -> Result<VolumeAndPan, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the volume and pan of the given track send or hardware output send. Also returns the correct value during the process of writing an automation envelope.

When choosing the send index, keep in mind that the hardware output sends (if any) come first.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_receive_ui_vol_pan(
    &self,
    track: MediaTrack,
    receive_index: u32
) -> Result<VolumeAndPan, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns the volume and pan of the given track receive. Also returns the correct value during the process of writing an automation envelope.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_send_ui_mute(
    &self,
    track: MediaTrack,
    send_index: u32
) -> Result<bool, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns whether the given track send or hardware output send is muted. Also returns the correct value during the process of writing an automation envelope.

When choosing the send index, keep in mind that the hardware output sends (if any) come first.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_receive_ui_mute(
    &self,
    track: MediaTrack,
    receive_index: u32
) -> Result<bool, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns whether the given track receive is muted. Also returns the correct value during the process of writing an automation envelope.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn toggle_track_send_ui_mute(
    &self,
    track: MediaTrack,
    send: TrackSendRef
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Toggles the mute state of the given track send, hardware output send or track receive.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_send_ui_vol(
    &self,
    track: MediaTrack,
    send: TrackSendRef,
    volume: ReaperVolumeValue,
    edit_mode: EditMode
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets the volume of the given track send, hardware output send or track receive.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_send_ui_pan(
    &self,
    track: MediaTrack,
    send: TrackSendRef,
    pan: ReaperPanValue,
    edit_mode: EditMode
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Sets the pan of the given track send, hardware output send or track receive.

Errors

Returns an error if the send doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_preset_index(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> TrackFxGetPresetIndexResultwhere
    UsageScope: MainThreadOnly,

Returns the index of the currently selected FX preset as well as the total preset count.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_preset_by_index(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    preset: FxPresetRef
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Selects a preset of the given track FX.

Errors

Returns an error e.g. if the FX doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_navigate_presets(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    increment: i32
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Navigates within the presets of the given track FX.

Errors

Returns an error e.g. if the FX doesn’t exist.

Safety

REAPER can crash if you pass an invalid track.

Example

use reaper_medium::ProjectContext::CurrentProject;
use reaper_medium::TrackFxLocation::NormalFxChain;

let track = session.reaper().get_track(CurrentProject, 0).ok_or("no tracks")?;
// Navigate 2 presets "up"
unsafe {
    session.reaper().track_fx_navigate_presets(track, NormalFxChain(0), -2)?
};

pub unsafe fn track_fx_get_preset(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    buffer_size: u32
) -> TrackFxGetPresetResultwhere
    UsageScope: MainThreadOnly,

Returns information about the currently selected preset of the given FX.

Currently selected means the preset which is currently showing in the REAPER dropdown.

With buffer size you can tell REAPER how many bytes of the preset name you want. If you are not interested in the preset name at all, pass 0.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_midi_input<R>(
    &self,
    device_id: MidiInputDeviceId,
    use_device: impl FnOnce(Option<&mut MidiInput>) -> R
) -> Rwhere
    UsageScope: AudioThreadOnly,

Grants temporary access to an already open MIDI input device.

Passes None to the given function if the device doesn’t exist, is not connected or is not already opened. The device must be enabled in REAPER’s MIDI preferences.

This function is typically called in the audio hook. But it’s also okay to call it in a VST plug-in as long as is_in_real_time_audio() returns true. If you are in the main thread and want to check if the device is open, use get_midi_input_is_open().

See audio hook for an example.

Design

The device is not just returned because then we would have to mark this function as unsafe. Returning the device would tempt the consumer to cache the pointer somewhere, which is bad because the MIDI device can appear/disappear anytime and REAPER doesn’t notify us about it. If we would call get_read_buf() on a cached pointer and the MIDI device is gone, REAPER would crash.

Calling this function in every audio hook invocation is fast enough and the official way to tap MIDI messages directly. Because of that we take a closure and pass a reference.

pub fn get_midi_input_is_open(&self, device_id: MidiInputDeviceId) -> boolwhere
    UsageScope: AnyThread,

Returns if the given device is open (enabled in REAPER’s MIDI preferences).

pub fn get_midi_output<R>(
    &self,
    device_id: MidiOutputDeviceId,
    use_device: impl FnOnce(Option<&MidiOutput>) -> R
) -> Rwhere
    UsageScope: AudioThreadOnly,

Grants temporary access to an already open MIDI output device.

Passes None to the given function if the device doesn’t exist, is not connected or is not already opened. The device must be enabled in REAPER’s MIDI preferences.

This function is typically called in the audio hook. But it’s also okay to call it in a VST plug-in as long as is_in_real_time_audio() returns true. If you are in the main thread and want to check if the device is open, use get_midi_output_is_open().

See audio hook for an example.

pub fn get_midi_output_is_open(&self, device_id: MidiOutputDeviceId) -> boolwhere
    UsageScope: AnyThread,

Returns if the given device is open (enabled in REAPER’s MIDI preferences).

pub fn parse_pan_str<'a>(
    &self,
    pan_string: impl Into<ReaperStringArg<'a>>
) -> ReaperPanValuewhere
    UsageScope: MainThreadOnly,

Parses the given string as pan value.

When in doubt, it returns 0.0 (center).

pub fn mk_pan_str(&self, value: ReaperPanValue) -> ReaperStringwhere
    UsageScope: MainThreadOnly,

Formats the given pan value.

pub fn mk_vol_str(&self, value: ReaperVolumeValue) -> ReaperStringwhere
    UsageScope: MainThreadOnly,

Formats the given volume value.

pub fn format_timestr_pos(
    &self,
    tpos: PositionInSeconds,
    buffer_size: u32,
    mode_override: TimeModeOverride
) -> ReaperStringwhere
    UsageScope: MainThreadOnly,

Formats the given position in time.

With buffer_size you can tell REAPER how many bytes of the time string you want.

Panics

Panics if the given buffer size is 0.

pub fn get_audio_device_info(
    &self,
    key: AudioDeviceAttributeKey<'_>,
    buffer_size: u32
) -> Result<ReaperString, ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Returns information about the currently open audio device.

With buffer_size you can tell REAPER how many bytes of the information you want.

Panics

Panics if the given buffer size is 0.

pub fn format_timestr_len(
    &self,
    tpos: DurationInSeconds,
    buffer_size: u32,
    offset: PositionInSeconds,
    mode_override: TimeModeOverride
) -> ReaperStringwhere
    UsageScope: MainThreadOnly,

Formats the given duration, starting from the given timeline position offset.

With buffer_size you can tell REAPER how many bytes of the time string you want.

Panics

Panics if the given buffer size is 0.

pub fn insert_media(
    &self,
    file: impl AsRef<Path>,
    mode: InsertMediaMode,
    flags: BitFlags<InsertMediaFlag>
) -> Result<(), ReaperFunctionError>where
    UsageScope: MainThreadOnly,

Inserts the given file as new media item.

Errors

Returns an error when inserting the file failed.

Trait Implementations

impl<UsageScope> Clone for Reaper<UsageScope>

fn clone(&self) -> Self

Returns a copy of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<UsageScope: Debug> Debug for Reaper<UsageScope>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<UsageScope: Default> Default for Reaper<UsageScope>

fn default() -> Reaper<UsageScope>

Returns the “default value” for a type.