Ultraschall Internals Documentation Reaper Internals Documentation Downloads Changelog of documentation Impressum and Contact
Ultraschall-logo Functions Engine GFX Engine Doc Engine Video Engine      
  Introduction/Concepts        Concepts      Concepts      Concepts
           Functions      Functions       Functions       Functions 

Jump to Index


^ API-Helper functions

get_action_context_MediaItemDiff  

^ Action Related Functions
ActionsList_GetAllActionsActionsList_GetSelectedActionsCheckActionCommandIDFormat
CheckActionCommandIDFormatCheckActionCommandIDFormat2GetAllActions
GetScriptFilenameFromActionCommandIDRefreshToolbar_ActionRunCommand
ToggleStateActionToggleStateButton 

^ Benchmark
Benchmark_GetAllStartTimesAndSlotsBenchmark_GetStartTimeBenchmark_MeasureTime

^ Child Scripts
GetScriptIdentifierGetScriptIdentifier_DescriptionGetScriptIdentifier_Title
GetScriptParametersGetScriptReturnvaluesGetScriptReturnvalues_Sender
MIDI_OnCommandByFilenameMain_OnCommandByFilenameMain_OnCommand_LuaCode
SetScriptIdentifier_DescriptionSetScriptIdentifier_TitleSetScriptParameters
SetScriptReturnvalues  

^ Config Vars
GetSetIntConfigVarSetIntConfigVar_Bitfield 

^ Data Analysis
FindPatternsInString  

^ Data Manipulation
AddIntToCharBase64_DecoderBase64_Encoder
CSV2IndividualLinesAsArrayCSV2LineCombineBytesToInteger
CompareArraysCompareStringWithAsciiValuesConcatIntegerIndexedTables
ConvertAscii2HexConvertBitsToIntegerConvertBitsToString
ConvertHex2AsciiConvertIntegerIntoString2ConvertIntegerToBits
ConvertStringToAscii_ArrayConvertStringToBitsConvertStringToIntegers
CountCharacterInStringCountEntriesInTable_MainCountLinesInString
CountPatternInStringCycleTableDB2MKVOL
EscapeMagicCharacters_StringGetAllEntriesFromTableGetDuplicatesFromArrays
GetPartialStringIsValidMatchingPatternKeepTableEntriesOfType
LimitFractionOfFloatMKVOL2DBMakeCopyOfTable
Notes2CSVRemoveTableEntriesOfTypeReplacePartOfString
ReplacePatternInStringReturnTableAsIndividualValuesReverseEndianess_Byte
ReverseTableRoundNumberSearchStringInString
SecondsToTimeSecondsToTimeString_hh_mm_ss_mssSetBitfield
SplitIntegerIntoBytesSplitStringAtLineFeedToArraySplitStringAtNULLBytes
StateChunkLayouterTimeStringToSeconds_hh_mm_ss_mssTimeToSeconds

^ Datatype-related
FloatCompareReturnTypeOfReaperObjecttoboolean
type  

^ Debug
PingMedeprecated 

^ Function Related
ConvertFunction_FromBase64StringConvertFunction_FromHexStringConvertFunction_ToBase64String
ConvertFunction_ToHexStringMakeFunctionUndoableRunLuaSourceCode
StoreFunctionInExtState  

^ Gmem/Shared Memory
GMem_GetValues_VideoSamplePeekerGMem_Read_ValueRangeGmem_GetCurrentAttachedName

^ LiceCap
SetLiceCapExeSetupLiceCap 

^ LoadFunctionFromExtState
LoadFunctionFromExtState  

^ ProgressBar
PrintProgressBarResetProgressBar 

^ ReaScript Console
BringReaScriptConsoleToFrontCloseReaScriptConsole 

^ Reaper Paths
GetReaperColorThemesPathGetReaperJSFXPathGetReaperScriptPath
GetReaperWebRCPath  

^ Shortcut Related
CharacterCodes_ReverseLookup  

^ Shortcut related
CharacterCodes_ReverseLookup_KBIniKBIniGetAllShortcuts 

^ String Output
printprint2print3
print_altprint_update 

^ Various Check Functions
IsItemInTrackIsItemInTrack2IsItemInTrack3
IsOS_MacIsOS_OtherIsOS_Windows
IsObjectValidReaperObjectIsValidGuidIsWithinTimeRange

^ Various
Create2DTableCreate3DTableCreateMultiDimTable
GetApiVersionGetOSGetReaperAppVersion
OpenURLPreventCreatingUndoPointReturnsMinusOneInCaseOfError_Arzala
RunBackgroundHelperFeaturesTimeToMeasuresget_action_context_MediaItemDiff

^ API-Variables

API_TempPathApi_InstallPathApi_Path
EuroSeparatorStartTime

^ Audio Management

GetHWInputs_AliasnamesGetHWOutputs_Aliasnames 

^ Automation Items

AutomationItem_DeleteAutomationItem_SplitAutomationItems_GetAll
AutomationItems_GetByTimeGetProject_AutomationItemStateChunkGetProject_CountAutomationItems

^ Clipboard Functions

FromClipGetMediaItemsFromClipboardGetStringFromClipboard_SWS
PutMediaItemsToClipboard_MediaItemArrayToClip 

^ Color Management

ApplyColorTableToItemColorsApplyColorTableToTrackColorsChangeColorBrightness
ChangeColorContrastChangeColorSaturationConvertColor
ConvertColorFromMacConvertColorFromWinConvertColorReverse
ConvertColorToGFXConvertColorToMacConvertColorToWin
ConvertGFXToColorCreateColorTableCreateSonicRainboomColorTable
IsValidColorTableRGB2Grayscale 

^ Configuration Settings


^ Menus
GetSetConfigActionMenu  

^ Preferences: Advanced UI
GetSetConfigAlwaysAllowKBGetSetConfigAudioCloseTrackWnds 

^ Preferences: Audio
GetSetConfigAllStereoPairsGetSetConfigAudioCloseStop 

^ Preferences: Device
GetSetConfigAudioThreadPr  

^ Preferences: Media
GetSetConfigApplyFXTail  

^ Preferences: Mute/Solo
GetSetConfigAutoMuteGetSetConfigAutoMuteFlags 

^ Preferences: Project
GetSetConfigAutoSaveIntGetSetConfigAutoSaveMode 

^ Preferences: Recording
GetSetConfigAdjRecLatGetSetConfigAdjRecManLatGetSetConfigAdjRecManLatIn

^ Preferences: Video/REX/Misc
GetSetConfigAcidImport  

^ Project Settings: Media
GetSetConfigAfxCfg  

^ Recording
GetStartNewFileRecSizeStateSetStartNewFileRecSizeState 

^ Transport: Contextmenu
GetSetConfigAudioPrShift  

^ Configuration-Files Management


^ Ini-Files
CountIniFileExternalState_keyCountIniFileExternalState_secCountKeysByPattern
CountSectionsByPatternCountValuesByPatternEnumerateIniFileExternalState_key
EnumerateIniFileExternalState_secEnumerateKeysByPatternEnumerateSectionsByPattern
EnumerateValuesByPatternGetIniFileExternalStateGetIniFileValue
SetIniFileExternalStateSetIniFileValue 

^ Reaper-kb.ini
CountKBIniActionsCountKBIniKeysCountKBIniScripts
DeleteKBIniActionsDeleteKBIniKeysDeleteKBIniScripts
GetActionCommandIDByFilenameGetKBIniActionsGetKBIniActionsID_ByActionCommandID
GetKBIniFilepathGetKBIniKeysGetKBIniKeys_ByActionCommandID
GetKBIniScriptsGetKBIniScripts_ByActionCommandIDQueryKeyboardShortcutByKeyID
SetKBIniActionsSetKBIniKeysSetKBIniScripts

^ Defer-Management

DeferGetDeferCycleSettingsGetDeferRunState
SetDeferCycleSettingsStopDeferCycle 

^ Developer


^ Error Handling
AddErrorMessageCountErrorMessage_FuncnameCountErrorMessages
DeleteAllErrorMessagesDeleteErrorMessageDeleteLastErrorMessage
GetErrorMessage_FuncnameGetLastErrorMessageGetLastErrorMessage2
GetLastErrorMessage_FuncnameReadErrorMessageSFEM
SLEMShowErrorMessagesInReascriptConsoleShowLastErrorMessage
SuppressErrorMessagesToggleIDE_Errormessages 

^ Helper functions
APIExistsApiTestEditReaScript
RFRRLRRRR

^ Envelope Management

ActivateTrackPanEnvActivateTrackPanEnv_TrackObjectActivateTrackPreFXPanEnv
ActivateTrackPreFXPanEnv_TrackObjectActivateTrackPreFXVolumeEnvActivateTrackPreFXVolumeEnv_TrackObject
ActivateTrackTrimVolumeEnvActivateTrackTrimVolumeEnv_TrackObjectActivateTrackVolumeEnv
ActivateTrackVolumeEnv_TrackObject  

^ Envelopes
GetAllTakeEnvelopesGetAllTrackEnvelopesGetTakeEnvelopeUnderMouseCursor
GetTakeEnvelopeUnderMouseCursorIsAnyMuteEnvelopeVisibleIsEnvelope_Track
IsTrackEnvelopeVisible_ArrangeView  

^ Get Envelope States
GetArmState_EnvelopeGetEnvelopeState_ActGetEnvelopeState_DefShape
GetEnvelopeState_EnvNameGetEnvelopeState_LaneHeightGetEnvelopeState_NumbersOnly
GetEnvelopeState_PTGetEnvelopeState_PooledEnvInstanceGetEnvelopeState_Vis
GetEnvelopeState_Voltype  

^ Get Envelope
GetAllTrackEnvelopesGetClosestEnvelopePointIDX_ByTimeGetEnvelopePoint
GetEnvelopePointIDX_BetweenGetLastEnvelopePoint_TrackEnvelope 

^ Helper functions
ActivateEnvelopeCheckEnvelopePointObjectCountEnvelopePoints
CreateEnvelopePointObjectGetTrackEnvelope_ClickStateGetTrackEnvelope_ClickState
IsValidEnvStateChunkIsValidEnvelopePointArrayIsValidEnvelopePointObject

^ Set Envelope States
SetArmState_EnvelopeSetEnvelopeState_ActSetEnvelopeState_DefShape
SetEnvelopeState_LaneHeightSetEnvelopeState_Vis 

^ Set Envelope
AddEnvelopePoints_EnvelopePointArrayAddEnvelopePoints_EnvelopePointObjectDeleteEnvelopePoints_EnvelopePointArray
DeleteEnvelopePoints_EnvelopePointObjectMoveTrackEnvelopePointsBySetEnvelopeHeight
SetEnvelopePoints_EnvelopePointArraySetEnvelopePoints_EnvelopePointObject 

^ Event Manager

EventManager_AddEventEventManager_AddStartupEventEventManager_CountRegisteredEvents
EventManager_CountStartupEventsEventManager_DebugModeEventManager_DebugMode_UserSpace
EventManager_EnumerateEventsEventManager_EnumerateEvents2EventManager_EnumerateStartupEvents
EventManager_EnumerateStartupEvents2EventManager_GetEventIdentifierEventManager_GetLastCheckfunctionState
EventManager_GetLastCheckfunctionState2EventManager_GetLastUpdateTimeEventManager_GetPausedState
EventManager_GetPausedState2EventManager_GetRegisteredEventIDEventManager_IsValidEventIdentifier
EventManager_PauseEventEventManager_RemoveAllEvents_ScriptEventManager_RemoveEvent
EventManager_RemoveStartupEventEventManager_RemoveStartupEvent2EventManager_ResumeEvent
EventManager_SetEventEventManager_SetStartupEventEventManager_Start
EventManager_Stop  

^ FX-Management


^ FXStateChunks
CountFXFromFXStateChunkCountFXStateChunksInStateChunkGetAllRFXChainfilenames
GetFXStateChunkIsValidFXStateChunkLoadFXStateChunkFromRFXChainFile
RemoveFXStateChunkFromItemStateChunkRemoveFXStateChunkFromTrackStateChunkSaveFXStateChunkAsRFXChainfile
SetFXStateChunk  

^ Get States
GetDocked_FXStateChunkGetFXBypass_FXStateChunkGetFXComment_FXStateChunk
GetFXFloatPos_FXStateChunkGetFXFromFXStateChunkGetFXGuid_FXStateChunk
GetFXMidiPreset_FXStateChunkGetFXSettingsString_FXLinesGetFXWak_FXStateChunk
GetLastSel_FXStateChunkGetShow_FXStateChunkGetTakeFXComment
GetTakeFX_AlternativeNameGetTrackFXCommentGetTrackFX_AlternativeName
GetWndRect_FXStateChunk  

^ Helper functions
GetFocusedFXGetLastTouchedFXGetRecentFX

^ InputFX
InputFX_AddByNameInputFX_CopyFXInputFX_CopyFXFromTakeFX
InputFX_CopyFXFromTrackFXInputFX_CopyFXToTakeFXInputFX_CopyFXToTrackFX
InputFX_DeleteInputFX_EndParamEditInputFX_FormatParamValue
InputFX_FormatParamValueNormalizedInputFX_GetChainVisibleInputFX_GetComment
InputFX_GetCountInputFX_GetEQInputFX_GetEQBandEnabled
InputFX_GetEQParamInputFX_GetEnabledInputFX_GetFXChain
InputFX_GetFXGUIDInputFX_GetFXNameInputFX_GetFloatingWindow
InputFX_GetFormattedParamValueInputFX_GetIOSizeInputFX_GetNamedConfigParm
InputFX_GetNumParamsInputFX_GetOfflineInputFX_GetOpen
InputFX_GetParamInputFX_GetParamExInputFX_GetParamName
InputFX_GetParamNormalizedInputFX_GetParameterStepSizesInputFX_GetPinMappings
InputFX_GetPresetInputFX_GetPresetIndexInputFX_GetUserPresetFilename
InputFX_MoveFXInputFX_MoveFXFromTakeFXInputFX_MoveFXFromTrackFX
InputFX_MoveFXToTakeFXInputFX_MoveFXToTrackFXInputFX_NavigatePresets
InputFX_QueryFirstFXIndexInputFX_SetEQBandEnabledInputFX_SetEQParam
InputFX_SetEnabledInputFX_SetFXChainInputFX_SetOffline
InputFX_SetOpenInputFX_SetParamInputFX_SetParamNormalized
InputFX_SetPinMappingsInputFX_SetPresetInputFX_SetPresetByIndex
InputFX_Show  

^ Parameter Mapping Alias
AddParmAlias_FXStateChunkCountParmAlias_FXStateChunkDeleteParmAlias2_FXStateChunk
DeleteParmAlias_FXStateChunkGetAllParmAliasNames_FXStateChunkGetParmAlias2_FXStateChunk
GetParmAlias_FXStateChunkGetParmAlias_MediaTrackSetParmAlias2_FXStateChunk
SetParmAlias_FXStateChunk  

^ Parameter Mapping LFOLearn
AddParmLFOLearn_FXStateChunkCountParmLFOLearn_FXStateChunkDeleteParmLFOLearn_FXStateChunk
GetParmLFOLearn_FXStateChunkGetParmLFOLearn_MediaItemGetParmLFOLearn_MediaTrack
SetParmLFOLearn_FXStateChunk  

^ Parameter Mapping Learn
AddParmLearn_FXStateChunkAddParmLearn_FXStateChunk2AddParmLearn_FXStateChunk2
CountParmLearn_FXStateChunkDeleteParmLearn2_FXStateChunkDeleteParmLearn_FXStateChunk
GetParmLearn_FXStateChunkGetParmLearn_FXStateChunk2GetParmLearn_FXStateChunk2
GetParmLearn_MediaItemGetParmLearn_MediaTrackSetParmLearn_FXStateChunk
SetParmLearn_FXStateChunk2SetParmLearn_FXStateChunk2 

^ Parameter Modulation
AddParmMod_ParmModTableCountParmModFromFXStateChunkCreateDefaultParmModTable
DeleteParmModFromFXStateChunkGetParmModTable_FXStateChunkGetParmModulationChunk_FXStateChunk
IsValidParmModTableSetParmMod_ParmModTable 

^ Plugins
AutoDetectVSTPluginsFolderScanDXPluginsScanVSTPlugins

^ Set States
SetDocked_FXStateChunkSetFXBypass_FXStateChunkSetFXComment_FXStateChunk
SetFXFloatPos_FXStateChunkSetFXGuid_FXStateChunkSetFXMidiPreset_FXStateChunk
SetFXWak_FXStateChunkSetLastSel_FXStateChunkSetShow_FXStateChunk
SetTakeFXCommentSetTakeFX_AlternativeNameSetTrackFXComment
SetTrackFX_AlternativeNameSetWndRect_FXStateChunk 

^ File Management


^ Background Copy
CopyFile_AddFileToQueueCopyFile_FlushCopiedFilesCopyFile_GetBufferSize
CopyFile_GetCopiedStatusCopyFile_GetCurrentlyCopiedFileCopyFile_GetCurrentlyRunningCopyInstances
CopyFile_GetPausedStateCopyFile_GetRemainingFilesToCopyCopyFile_IsCurrentlyCopying
CopyFile_PauseCopyFile_SetBufferSizeCopyFile_StartCopying
CopyFile_StopCopying  

^ File Analysis
CheckForValidFileFormatsCountLinesInFileGetLengthOfFile
OnlyFilesOfCertainType  

^ Helper functions
CountDirectoriesAndFilesInPathCreateValidTempFileDirectoryExists
DirectoryExists2GetAllDirectoriesInPathGetAllFilenamesInPath
GetAllRecursiveFilesAndSubdirectoriesGetPathGetReaperWorkDir
SetReaperWorkDir  

^ Manipulate Files
MakeCopyOfFileMakeCopyOfFile_Binary 

^ Misc
BatchConvertFiles  

^ Read Files
ReadBinaryFileFromPatternReadBinaryFileUntilPatternReadBinaryFile_Offset
ReadFileAsLines_ArrayReadFullFileReadLinerangeFromFile
ReadSubtitles_SRTReadSubtitles_VTTReadValueFromFile

^ Write Files
SaveSubtitles_SRTWriteValueToFileWriteValueToFile_Insert
WriteValueToFile_InsertBinaryWriteValueToFile_ReplaceWriteValueToFile_ReplaceBinary

^ Image File Handling

CaptureScreenAreaAsPNGCaptureWindowAsPNGConvertJPG2PNG
ConvertPNG2JPGResizeJPGResizePNG

^ Localization

LocalizeLocalize_RefreshFileLocalize_UseFile

^ MIDI Management


^ MIDI Editor
OpenItemInMidiEditorZoomHorizontal_MidiEditorZoomVertical_MidiEditor

^ Notes
MIDI_SendMidiCCMIDI_SendMidiNoteMIDI_SendMidiPC
MIDI_SendMidiPitchQueryMIDIMessageNameByID 

^ Manipulate Files

MoveFileOrFolder  

^ Markers


^ Assistance functions
CountMarkersAndRegionsGetGuidFromMarkerIDGetMarkerByScreenCoordinates
GetMarkerByTimeGetMarkerIDFromGuidGetMarkerUpdateCounter
GetNextFreeRegionIndexGetRegionByScreenCoordinatesGetRegionByTime
GetTimeSignaturesByScreenCoordinatesGetTimeSignaturesByTimeIsMarkerAtPosition
IsRegionAtPositionMoveMarkersByMoveRegionsBy
ParseMarkerStringRenumerateMarkers 

^ Custom Markers
AddCustomMarkerAddCustomRegionCountAllCustomMarkers
CountAllCustomRegionsDeleteCustomMarkersDeleteCustomRegions
EnumerateCustomMarkersEnumerateCustomRegionsGetAllCustomMarkerNames
GetAllCustomMarkersGetAllCustomRegionNamesGetAllCustomRegions
IsMarkerValidCustomMarkerIsRegionValidCustomRegionSetCustomMarker
SetCustomRegion  

^ Edit Markers and Regions
AddEditMarkerAddEditRegionCountEditMarkers
CountEditRegionsDeleteEditMarkerDeleteEditRegion
EditToMarkerEnumerateEditMarkersEnumerateEditRegion
ExportEditMarkersToFileGetAllEditMarkersImportEditFromFile
IsMarkerEditIsRegionEditRegionMarkerToEditMarker
SetEditMarkerSetEditRegion 

^ General Markers and Regions
GetAllMarkersGetAllMarkersBetweenGetAllRegions
GetAllRegionsBetweenGetLastMarkerPositionGetLastRegion
GetMarkerAndRegionsByIndexGetMarkerByNameGetMarkerByName_Pattern
ImportMarkersFromFileRippleCut_RegionsSetMarkerByIndex

^ Normal Markers
AddNormalMarkerCountNormalMarkersCountNormalMarkers_NumGap
DeleteNormalMarkerEnumerateNormalMarkersExportNormalMarkersToFile
GetAllNormalMarkersIsMarkerNormalSetNormalMarker

^ PodRange Region
AddPodRangeRegionDeletePodRangeRegionGetPodRangeRegion
IsRegionPodrangeSetPodRangeRegion 

^ Time Signature Markers
GetAllTimeSigMarkersGetLastTimeSigMarkerPositionIsTimeSigmarkerAtPosition
MoveTimeSigMarkersBy  

^ Media Explorer

MediaExplorer_OnCommandUpdateMediaExplorer 

^ MediaItem Management


^ Assistance functions
ApplyActionToMediaItemApplyActionToMediaItemArrayApplyActionToMediaItemArray2
ApplyActionToMediaItemTakeApplyFunctionToMediaItemArrayCheckMediaItemArray
CheckMediaItemStateChunkArrayCopyMediaItemToDestinationTrackGetAllMediaItemAttributes_Table
GetAllMediaItemGUIDsGetEndOfItemGetGapsBetweenItems
GetItem_ClickStateGetItem_HighestRecCounterGetItem_Number
GetMediaItemArrayLengthGetMediaItemStateChunkArrayLengthGetMediaItemStateChunksFromItems
GetMediaItemStateChunksFromMediaItemArrayGetMediafileAttributesGetParentTrack_MediaItem
IsItemInTimerangeIsItemVisibleIsSplitAtPosition
IsValidMediaItemArrayIsValidMediaItemStateChunkIsValidMediaItemStateChunkArray
OnlyItemsInTracksAndTimerangeOnlyMediaItemsOfTracksInTrackstringOnlyMediaItemsOfTracksInTrackstring_StateChunk
PreviewMediaFilePreviewMediaItemSetAllMediaItemAttributes_Table
StopAnyPreview  

^ Delete
DeleteMediaItemDeleteMediaItemsFromArrayDeleteMediaItems_Position
DeleteMediaItems_Position  

^ Edit
RippleCutRippleCut_ReverseSectionCut
SectionCut_InverseSplitItemsAtPositionFromArraySplitMediaItems_Position

^ Get MediaItem States
GetItemAllTakesGetItemBeatGetItemChanMode
GetItemFadeFlagGetItemFadeInGetItemFadeOut
GetItemGUIDGetItemGroupGetItemIGUID
GetItemIIDGetItemImageGetItemLength
GetItemLockGetItemLoopGetItemMixFlag
GetItemMuteGetItemNameGetItemPlayRate
GetItemPositionGetItemRecPassGetItemSampleOffset
GetItemSelectedGetItemSnapOffsetGetItemStateChunk
GetItemUSTrackNumber_StateChunkGetItemVolPanGetItem_Video_IgnoreAudio

^ Get MediaItems
EnumerateMediaItemsInTrackGetAllLockedItemsFromMediaItemArrayGetAllMediaItems
GetAllMediaItemsBetweenGetAllMediaItemsFromTrackGetAllMediaItemsInTimeSelection
GetAllSelectedMediaItemsBetweenGetMediaItemsAtPosition 

^ Insert
InsertImageFileInsertMediaItemArrayInsertMediaItemFromFile
InsertMediaItemStateChunkArrayInsertMediaItem_MediaItemInsertMediaItem_MediaItemStateChunk
RippleInsertRippleInsert_MediaItemStateChunks 

^ Manipulate
AddLockStateToMediaItemStateChunkAddLockStateTo_MediaItemStateChunkArrayApplyStateChunkToItems
ChangeDeltaLengthOfMediaItems_FromArrayChangeDeltaOffsetOfMediaItems_FromArrayChangeLengthOfMediaItems_FromArray
ChangeOffsetOfMediaItems_FromArrayMoveMediaItemsAfter_ByMoveMediaItemsBefore_By
MoveMediaItemsBetween_ToMoveMediaItems_FromArrayNormalizeItems
SetItemsLockState  

^ MediaItem-Takes
CountMediaItemTake_StateChunkGetItemSourceFile_TakeGetMediaItemTake
GetMediaItemTake_StateChunkGetTake_ReverseState 

^ Outtakes Vault
MediaItems_Outtakes_AddSelectedItemsMediaItems_Outtakes_GetAllItemsMediaItems_Outtakes_InsertAllItems

^ Selected Items
DeselectMediaItems_MediaItemArrayGetAllSelectedMediaItemsGetSelectedMediaItemsAtPosition
GetSelectedMediaItemsBetweenSelectMediaItems_MediaItemArraySetMediaItemsSelected_TimeSelection

^ Set MediaItem States
SetItemImageSetItemLengthSetItemPosition
SetItemUSTrackNumber_StateChunkSetItem_Video_IgnoreAudioSetMediaItemStateChunk_in_TrackStateChunk

^ Spectral Edit
AddItemSpectralEditCountItemSpectralEditsDeleteItemSpectralEdit
GetItemSpectralConfigGetItemSpectralConfig2GetItemSpectralConfig2
GetItemSpectralEditGetItemSpectralEdit2GetItemSpectralVisibilityState
SetItemSpectralConfigSetItemSpectralEditSetItemSpectralVisibilityState

^ Metadata Management


^ Extension States Guid
GetGuidExtStateSetGuidExtState 

^ Extension States
DeleteProjExtState_KeyDeleteProjExtState_SectionGetProjExtState_AllKeyValues
ProjExtState_CountAllKeys  

^ Markers
GetMarkerExtStateSetMarkerExtState 

^ Reaper Metadata Management
Metadata_GetAllPresetNamesMetadata_GetMetaDataTable_Presets 

^ Tags
Metadata_AIFF_GetSetMetadata_APE_GetSetMetadata_BWF_GetSet
Metadata_CART_GetSetMetadata_CUE_GetSetMetadata_ID3_GetSet
Metadata_INFO_GetSetMetadata_IXML_GetSetMetadata_VORBIS_GetSet
Metadata_XMP_GetSet  

^ Miscellaneous

WinterlySnowflakes  

^ Mute Management


^ Mute Lane
ActivateMuteActivateMute_TrackObjectDeactivateMute
DeactivateMute_TrackObject  

^ Muting tracks within envelope-lanes
CountMuteEnvelopePointsDeleteMuteStateDeleteMuteState_TrackObject
GetNextMuteStateGetNextMuteState_TrackObjectGetPreviousMuteState
GetPreviousMuteState_TrackObjectIsMuteAtPositionIsMuteAtPosition_TrackObject
ToggleMuteToggleMute_TrackObject 

^ Navigation

CenterViewToCursorGetClosestGoToPointsGetClosestNextMarker
GetClosestNextRegionEdgeGetClosestPreviousMarkerGetClosestPreviousRegionEdge
GetLastCursorPositionGetLastLoopStateGetLastPlayState
GetNextClosestItemEdgeGetPreviousClosestItemEdgeJumpBackwardBy
JumpBackwardBy_RecordingJumpForwardByJumpForwardBy_Recording
SetPlayAndEditCursor_WhenPlayingSetPlayCursor_WhenPlayingToggleScrollingDuringPlayback

^ Scrubbing
Scrubbing_MoveCursor_GetToggleStateScrubbing_MoveCursor_Toggle 

^ Transport
GetLoopStateSetLoopState 

^ Project-Files


^ Helper functions
GetProjectStateChunkGetProject_RenderOutputPath 

^ RPP-Files Set
SetProject_GroupOverride  

^ Project-Management


^ AutoSave
AutoSave_GetMinutesAutoSave_GetOptionsAutoSave_SetMinutes
AutoSave_SetOptions  

^ Helper functions
CheckForChangedProjectTabsConvertOldProjectToCurrentReaperVersionCountProjectTabs
CreateTemporaryFileOfProjectfileEnumProjectsGetCurrentTimeLengthOfFrame
GetLengthOfFramesGetProjectFilenameGetProjectLength
GetProject_LengthGetProject_LengthGetProject_Tabs
GetRecentProjectsIsTimeSelectionActiveIsValidProjectStateChunk
IsValidReaProjectNewProjectTab 

^ ProjectBay
GetAllMediaItems_FromProjectBayStateChunkIsValidProjectBayStateChunk 

^ RPP-Files Get
GetProjectState_NumbersOnlyGetProject_AddMediaToProjectAfterRenderGetProject_ApplyFXCFG
GetProject_AuthorGetProject_AutoCrossFadeGetProject_CountMarkersAndRegions
GetProject_CountMasterHWOutsGetProject_CursorPosGetProject_DefPitchMode
GetProject_EnvAttachGetProject_ExtensionsGetProject_Feedback
GetProject_GetMarkerGetProject_GetRegionGetProject_GlobalAuto
GetProject_GridGetProject_GroupDisabledGetProject_GroupName
GetProject_GroupOverrideGetProject_HorizontalZoomGetProject_ItemMixBehavior
GetProject_LockGetProject_LoopGetProject_LoopGran
GetProject_MarkersAndRegionsGetProject_MasterAutomodeGetProject_MasterDualPanEnv2StateChunk
GetProject_MasterDualPanEnvL2StateChunkGetProject_MasterDualPanEnvLStateChunkGetProject_MasterDualPanEnvStateChunk
GetProject_MasterFXBypGetProject_MasterFXListStateChunkGetProject_MasterGroupFlagsHighState
GetProject_MasterGroupFlagsStateGetProject_MasterHWOutGetProject_MasterHWPanEnvStateChunk
GetProject_MasterHWVolEnvStateChunkGetProject_MasterMuteSoloGetProject_MasterNChans
GetProject_MasterPanModeGetProject_MasterPanMode_ExGetProject_MasterPlayspeed
GetProject_MasterSelGetProject_MasterTrackColorGetProject_MasterTrackHeight
GetProject_MasterTrackViewGetProject_MasterVolEnv2StateChunkGetProject_MasterVolEnv3StateChunk
GetProject_MasterVolEnvStateChunkGetProject_MasterVolumeGetProject_MasterWidth
GetProject_MaxProjectLengthGetProject_MetaDataStateChunkGetProject_Metronome
GetProject_MixerUIFlagsGetProject_NumberOfTracksGetProject_PanLaw
GetProject_PanModeGetProject_PeakGainGetProject_Playrate
GetProject_PooledEnvAttachGetProject_ProjOffsetsGetProject_ProjectBay
GetProject_QRenderOriginalProjectGetProject_QRenderOutFilesGetProject_ReaperVersion
GetProject_RecModeGetProject_RecPathGetProject_RecordCFG
GetProject_RenderCFGGetProject_RenderDitherStateGetProject_RenderFilename
GetProject_RenderFreqNChansGetProject_RenderPatternGetProject_RenderQueueDelay
GetProject_RenderRangeGetProject_RenderResampleGetProject_RenderSpeed
GetProject_RenderStemsGetProject_Render_NormalizeGetProject_RippleState
GetProject_SMPTESyncGetProject_SampleRateGetProject_Selection
GetProject_TakeLaneGetProject_TempoGetProject_TempoEnvEx
GetProject_TempoEnv_ExStateChunkGetProject_TempoTimeSignatureGetProject_TimeBase
GetProject_TimemodeGetProject_TrackMixingDepthGetProject_TrackStateChunk
GetProject_UseRecConfigGetProject_VerticalZoomGetProject_VideoConfig

^ RPP-Files Set
SetProject_AddMediaToProjectAfterRenderSetProject_ApplyFXCFGSetProject_AutoCrossFade
SetProject_CursorPosSetProject_DefPitchModeSetProject_EnvAttach
SetProject_FeedbackSetProject_GlobalAutoSetProject_Grid
SetProject_HorizontalZoomSetProject_ItemMixBehaviorSetProject_Lock
SetProject_LoopSetProject_LoopGranSetProject_MasterAutomode
SetProject_MasterFXBypSetProject_MasterMuteSoloSetProject_MasterNChans
SetProject_MasterPanModeSetProject_MasterSelSetProject_MasterTrackColor
SetProject_MasterTrackHeightSetProject_MasterTrackViewSetProject_MaxProjectLength
SetProject_MixerUIFlagsSetProject_PanLawSetProject_PanMode
SetProject_PeakGainSetProject_PlayrateSetProject_ProjOffsets
SetProject_RecModeSetProject_RecPathSetProject_RecordCFG
SetProject_RenderCFGSetProject_RenderDitherStateSetProject_RenderFilename
SetProject_RenderFreqNChansSetProject_RenderPatternSetProject_RenderQueueDelay
SetProject_RenderRangeSetProject_RenderResampleSetProject_RenderSpeed
SetProject_RenderStemsSetProject_Render_NormalizeSetProject_RippleState
SetProject_SMPTESyncSetProject_SampleRateSetProject_Selection
SetProject_TakeLaneSetProject_TempoSetProject_TempoTimeSignature
SetProject_TimeBaseSetProject_TimemodeSetProject_TrackMixingDepth
SetProject_UseRecConfigSetProject_VerticalZoomSetProject_VideoConfig

^ Razor Edit

RazorEdit_GetAllRazorEditsRazorEdit_ProjectHasRazorEdit 

^ ReaMote

AutoSearchReaMoteClients  

^ Reaper Element Positions


^ Reaper Window
ConvertClient2ScreenXCoordinate_ReaperWindowConvertScreen2ClientXCoordinate_ReaperWindowSetReaperWindowToSize

^ Rendering Projects


^ Analyzing Renderstrings
GetOutputFormat_RenderCfgGetRenderCFG_Settings_AIFFGetRenderCFG_Settings_AVI_Video
GetRenderCFG_Settings_AudioCDGetRenderCFG_Settings_DDPGetRenderCFG_Settings_FLAC
GetRenderCFG_Settings_GIFGetRenderCFG_Settings_LCFGetRenderCFG_Settings_M4AMac
GetRenderCFG_Settings_MKV_VideoGetRenderCFG_Settings_MOVMac_VideoGetRenderCFG_Settings_MP3
GetRenderCFG_Settings_MP3ABRGetRenderCFG_Settings_MP3CBRGetRenderCFG_Settings_MP3MaxQuality
GetRenderCFG_Settings_MP3VBRGetRenderCFG_Settings_MP4Mac_VideoGetRenderCFG_Settings_OGG
GetRenderCFG_Settings_OPUSGetRenderCFG_Settings_QTMOVMP4_VideoGetRenderCFG_Settings_WAV
GetRenderCFG_Settings_WAVPACKGetRenderCFG_Settings_WebMVideo 

^ Assistance functions
ApplyRenderTable_ProjectApplyRenderTable_ProjectFileAreRenderTablesEqual
CreateNewRenderTableGetLastRenderPathsGetLastUsedRenderPatterns
GetRenderTable_ProjectGetRenderTable_ProjectFileIsReaperRendering
IsValidRenderTableResolveRenderPattern 

^ Creating Renderstrings
CreateRenderCFG_AIFFCreateRenderCFG_AVI_VideoCreateRenderCFG_AudioCD
CreateRenderCFG_DDPCreateRenderCFG_FLACCreateRenderCFG_GIF
CreateRenderCFG_LCFCreateRenderCFG_M4AMACCreateRenderCFG_MKV_Video
CreateRenderCFG_MOVMAC_VideoCreateRenderCFG_MP3ABRCreateRenderCFG_MP3CBR
CreateRenderCFG_MP3MaxQualityCreateRenderCFG_MP3VBRCreateRenderCFG_MP4MAC_Video
CreateRenderCFG_OGGCreateRenderCFG_OpusCreateRenderCFG_QTMOVMP4_Video
CreateRenderCFG_WAVCreateRenderCFG_WAVPACKCreateRenderCFG_WebMVideo

^ Loudness Calculation
CalculateLoudness  

^ Render Presets
AddRenderPresetDeleteRenderPreset_BoundsDeleteRenderPreset_FormatOptions
GetRenderPreset_NamesGetRenderPreset_RenderTableSetRenderPreset

^ Render Settings
GetRender_AddRenderedFilesToProjectGetRender_AutoIncrementFilenameGetRender_EmbedMetaData
GetRender_EmbedStretchMarkersGetRender_NoSilentFilesGetRender_OfflineOnlineMode
GetRender_ProjectSampleRateForMixGetRender_QueueDelayGetRender_ResampleMode
GetRender_SaveCopyOfProjectGetRender_TailLengthSetRender_AddRenderedFilesToProject
SetRender_AutoIncrementFilenameSetRender_EmbedMetaDataSetRender_EmbedStretchMarkers
SetRender_NoSilentFilesSetRender_OfflineOnlineModeSetRender_ProjectSampleRateForMix
SetRender_QueueDelaySetRender_ResampleModeSetRender_SaveCopyOfProject
SetRender_TailLength  

^ RenderQueue
AddProjectFileToRenderQueueAddSelectedItemsToRenderQueueGetRenderQueuedProjects
RenderProject_RenderQueue  

^ Rendering any Outputformat
RenderProjectRenderProject_RegionsRenderProject_RenderTable
Render_Loop  

^ Themeing

ApplyAllThemeLayoutParametersGetAllThemeLayoutNamesGetAllThemeLayoutParameters
GetThemeParameterIndexByDescriptionGetThemeParameterIndexByNameSetThemeParameterIndexByDescription
SetThemeParameterIndexByName  

^ Default v6-Theme
Theme_Defaultv6_GetEnvFaderSizeTheme_Defaultv6_GetEnvFolderIndentTheme_Defaultv6_GetEnvNameSize
Theme_Defaultv6_GetEnvSizeTheme_Defaultv6_GetHideTCPElementTheme_Defaultv6_GetMCPAlignControls
Theme_Defaultv6_GetMCPBorderStyleTheme_Defaultv6_GetMCPFolderIndentTheme_Defaultv6_GetMCPMeterExpansion
Theme_Defaultv6_GetMCPSizeAndLayoutTheme_Defaultv6_GetStyleMCPElementTheme_Defaultv6_GetTCPAlignControls
Theme_Defaultv6_GetTCPFolderIndentTheme_Defaultv6_GetTCPInputSizeTheme_Defaultv6_GetTCPMeterLocation
Theme_Defaultv6_GetTCPMeterSizeTheme_Defaultv6_GetTCPNameSizeTheme_Defaultv6_GetTCPSizeAndLayout
Theme_Defaultv6_GetTCPVolumeSizeTheme_Defaultv6_GetTransPlayRateSizeTheme_Defaultv6_GetTransSize
Theme_Defaultv6_SetEnvFaderSizeTheme_Defaultv6_SetEnvFolderIndentTheme_Defaultv6_SetEnvNameSize
Theme_Defaultv6_SetEnvSizeTheme_Defaultv6_SetHideTCPElementTheme_Defaultv6_SetMCPAlignControls
Theme_Defaultv6_SetMCPBorderStyleTheme_Defaultv6_SetMCPFolderIndentTheme_Defaultv6_SetMCPMeterExpansion
Theme_Defaultv6_SetMCPSizeAndLayoutTheme_Defaultv6_SetStyleMCPElementTheme_Defaultv6_SetTCPAlignControls
Theme_Defaultv6_SetTCPFolderIndentTheme_Defaultv6_SetTCPInputSizeTheme_Defaultv6_SetTCPMeterLocation
Theme_Defaultv6_SetTCPMeterSizeTheme_Defaultv6_SetTCPNameSizeTheme_Defaultv6_SetTCPSizeAndLayout
Theme_Defaultv6_SetTCPVolumeSizeTheme_Defaultv6_SetTransPlayRateSizeTheme_Defaultv6_SetTransSize

^ Track Management


^ Assistance functions
AddMediaItemStateChunk_To_TrackStateChunkAnyTrackFXBypassAnyTrackFreeItemPositioningMode
AnyTrackHiddenMCPAnyTrackHiddenTCPAnyTrackMute
AnyTrackPhasedAnyTrackRecMonitoredAnyTrackRecarmed
ApplyActionToTrackCountItemsInTrackStateChunkCreateTrackString
CreateTrackStringByGUIDCreateTrackStringByMediaTracksCreateTrackStringByTracknames
CreateTrackString_AllTracksCreateTrackString_ArmedTracksCreateTrackString_SelectedTracks
CreateTrackString_UnarmedTracksDeleteTracks_TrackStringGetAllMediaItemsFromTrackStateChunk
GetAllVisibleTracks_ArrangeGetItemStateChunkFromTrackStateChunkGetLengthOfAllMediaItems_Track
GetTrackLengthGetTracknumberByGuidInsertTrackAtIndex
InsertTrack_TrackStateChunkInverseTrackstringIsTrackObjectTracknumber
IsTrackVisibleIsValidTrackStateChunkIsValidTrackString
MoveTracksOnlyTracksInBothTrackstringsOnlyTracksInOneTrackstring
RemoveDuplicateTracksInTrackstringRemoveMediaItemByGUID_TrackStateChunkRemoveMediaItemByIGUID_TrackStateChunk
RemoveMediaItem_TrackStateChunk  

^ Get Track States
GetAllLockedTracksGetAllSelectedTracksGetTrackAutoRecArmState
GetTrackAutomodeStateGetTrackBeatStateGetTrackBusCompState
GetTrackBypFXStateGetTrackFreeModeStateGetTrackGroupFlagsState
GetTrackGroupFlags_HighStateGetTrackHeightStateGetTrackID
GetTrackINQStateGetTrackIPhaseStateGetTrackIcon_Filename
GetTrackIsBusStateGetTrackLayoutNamesGetTrackLockState
GetTrackMIDIOutStateGetTrackMainSendStateGetTrackMidiBankProgFn
GetTrackMidiCTLGetTrackMidiColorMapFnGetTrackMidiInputChanMap
GetTrackMidiTextStrFnGetTrackMuteSoloStateGetTrackNChansState
GetTrackNameGetTrackPanModeGetTrackPeakColorState
GetTrackPerfStateGetTrackRecCFGGetTrackRecState
GetTrackScoreGetTrackSelection_TrackStateChunkGetTrackShowInMixState
GetTrackStateChunk_TracknumberGetTrackState_NumbersOnlyGetTrackVUState
GetTrackVolPanGetTrackWidthSetTrackSelection_TrackStateChunk

^ Hardware Out
AddTrackHWOutApplyAllHWOutsAreHWOutsTablesEqual
ClearRoutingMatrixCountTrackHWOutsDeleteTrackHWOut
GetAllHWOutsGetTrackHWOutSetTrackHWOut

^ Send/Receive-Routing
AddTrackAUXSendReceivesApplyAllAUXSendReceivesApplyAllMainSendStates
AreAUXSendReceivesTablesEqualAreMainSendsTablesEqualClearRoutingMatrix
CountTrackAUXSendReceivesDeleteTrackAUXSendReceivesGetAllAUXSendReceives
GetAllMainSendStatesGetTrackAUXSendReceivesSetTrackAUXSendReceives

^ Set Track States
CollapseTrackHeightGetTrackByTrackNameSetAllTracksSelected
SetTrackAutoRecArmStateSetTrackAutomodeStateSetTrackBeatState
SetTrackBusCompStateSetTrackBypFXStateSetTrackFreeModeState
SetTrackGroupFlagsStateSetTrackGroupFlags_HighStateSetTrackHeightState
SetTrackIDSetTrackINQStateSetTrackIPhaseState
SetTrackIcon_FilenameSetTrackIsBusStateSetTrackLayoutNames
SetTrackLockStateSetTrackMIDIOutStateSetTrackMainSendState
SetTrackMidiBankProgFnSetTrackMidiCTLSetTrackMidiColorMapFn
SetTrackMidiInputChanMapSetTrackMidiTextStrFnSetTrackMuteSoloState
SetTrackNChansStateSetTrackNameSetTrackPanMode
SetTrackPeakColorStateSetTrackPerfStateSetTrackRecCFG
SetTrackRecStateSetTrackScoreSetTrackShowInMixState
SetTrackStateChunk_TracknumberSetTrackVUStateSetTrackVolPan
SetTrackWidthSetTrack_LastTouchedSetTrack_Trackheight_Force
SetTracksSelectedSetTracksToLockedSetTracksToUnlocked

^ TrackManager

TrackManager_ClearFilterTrackManager_OpenCloseTrackManager_SelectionFromList
TrackManager_SelectionFromProjectTrackManager_SetFilterTrackManager_ShowAll

^ Ultraschall Specific


^ Followmode
pause_follow_one_cycle  

^ Routing
GetAllAUXSendReceives2GetAllHWOuts2GetAllMainSendStates2

^ Soundboard
SoundBoard_PlaySoundBoard_PlayList_CurrentIndexSoundBoard_PlayList_Next
SoundBoard_PlayList_PreviousSoundBoard_PlayList_SetIndexSoundBoard_Stop
SoundBoard_StopAllSoundsSoundBoard_TogglePlayPauseSoundBoard_TogglePlayStop
SoundBoard_TogglePlay_FadeOutStopSoundboard_PlayFadeIn 

^ Track Management
GetTypeOfTrackIsTrackSoundboardIsTrackStudioLink
IsTrackStudioLinkOnAir  

^ Ultraschall.ini
CountUSExternalState_keyCountUSExternalState_secDeleteUSExternalState
EnumerateUSExternalState_keyEnumerateUSExternalState_secGetUSExternalState
SetUSExternalState  

^ User Interface

GetPreventUIRefreshCountPreventUIRefreshRestoreUIRefresh

^ Arrangeview Management
DeleteArrangeviewSnapshotGetVerticalScrollGetVerticalZoom
IsValidArrangeviewSnapshotRestoreArrangeviewSnapshotRetrieveArrangeviewSnapshot
SetVerticalRelativeScrollSetVerticalScrollSetVerticalZoom
StoreArrangeviewSnapshot  

^ Context Menus
ShowMenu  

^ Dialogs
BrowseForOpenFilesGetUserInputsMB

^ MediaItems
GetItemButtonsVisibleSetItemButtonsVisible 

^ Menu Management
ShowAutomationItemMenuShowEnvelopeMenuShowEnvelopePointMenu
ShowEnvelopePointMenu_AutomationItemShowMediaItemMenuShowRulerMenu
ShowTrackAreaMenuShowTrackInputMenuShowTrackPanelMenu
ShowTrackRoutingMenu  

^ Miscellaneous
ConvertYCoordsMac2WinGetIDEFontSizeGetTimeByMouseXPosition
GetUIScaleSetIDEFontSizeSetReaScriptConsole_FontStyle
SetUIScale  

^ Reaper-Windowhandler
GetActionsHWNDGetBatchFileItemConverterHWNDGetConsolidateTracksHWND
GetExportProjectMIDIHWNDGetHWND_ArrangeViewAndTimeLineGetMediaExplorerHWND
GetPreferencesHWNDGetProjectDirectoryCleanupHWNDGetProjectSettingsHWND
GetReaScriptConsoleWindowGetRenderQueueHWNDGetRenderToFileHWND
GetRenderingToFileHWNDGetSaveLiveOutputToDiskHWNDGetSaveProjectAsHWND
GetTrackManagerHWNDGetVideoHWND 

^ Screen Management
GetScreenHeightGetScreenWidth 

^ Track Control Panel(TCP)
GetTCPWidthTCP_SetWidth 

^ Transport and Ruler
SetTimeUnit  

^ Transport
GetPlayCursorWidthSetPlayCursorWidth 

^ UI-Elements
GetCheckboxStateSetCheckboxState 

^ Window Management
GetAllReaScriptIDEWindowsGetChildSizeWithinParentHWNDGetReaperWindowAttributes
GetTopmostHWNDHasHWNDChildWindowNamesIsValidHWND
MoveChildWithinParentHWNDReturnAllChildHWNDVideoWindow_FullScreenToggle
Windows_Find  

^ misc
GetHelpDisplayModeSetHelpDisplayModeWiringDiagram_GetOptions
WiringDiagram_SetOptions  

^ Web Interface

WebInterface_GetInstalledInterfaces  


^ Reaper version 5.975 Ultraschall version 4.00get_action_context_MediaItemDiff

Lua: MediaItem MediaItem, MediaItem_Take MediaItem_Take, MediaItem MediaItem_unlocked, boolean Item_moved, number StartDiffTime, number EndDiffTime, number LengthDiffTime, number OffsetDiffTime = ultraschall.get_action_context_MediaItemDiff(optional boolean exlude_mousecursorsize, optional integer x, optional integer y)

Returns the currently clicked MediaItem, Take as well as the difference of position, end, length and startoffset since last time calling this function.
Good for implementing ripple-drag/editing-functions, whose position depends on changes in the currently clicked MediaItem.
Repeatedly call this (e.g. in a defer-cycle) to get all changes made, during dragging position, length or offset of the MediaItem underneath mousecursor.

This function takes into account the size of the start/end-drag-mousecursor, that means: if mouse-position is within 3 pixels before start/after end of the item, it will get the correct MediaItem.
This is a workaround, as the mouse-cursor changes to dragging and can still affect the MediaItem, even though the mouse at this position isn't above a MediaItem anymore.
To be more strict, set exlude_mousecursorsize to true. That means, it will only detect MediaItems directly beneath the mousecursor. If the mouse isn't above a MediaItem, this function will ignore it, even if the mouse could still affect the MediaItem.
If you don't understand, what that means: simply omit exlude_mousecursorsize, which should work in almost all use-cases. If it doesn't work as you want, try setting it to true and see, whether it works now.    

Returnvalues:
MediaItem MediaItem
the MediaItem at the current mouse-position; nil if not found
MediaItem_Take MediaItem_Take
the MediaItem_Take underneath the mouse-cursor
MediaItem MediaItem_unlocked
if the MediaItem isn't locked, you'll get a MediaItem here. If it is locked, this retval is nil
boolean Item_moved
true, the item was moved; false, only a part(either start or end or offset) of the item was moved
number StartDiffTime
if the start of the item changed, this is the difference;
  positive, the start of the item has been changed towards the end of the project
  negative, the start of the item has been changed towards the start of the project
  0, no changes to the itemstart-position at all
number EndDiffTime
if the end of the item changed, this is the difference;
  positive, the end of the item has been changed towards the end of the project
  negative, the end of the item has been changed towards the start of the project
  0, no changes to the itemend-position at all
number LengthDiffTime
if the length of the item changed, this is the difference;
  positive, the length is longer
  negative, the length is shorter
  0, no changes to the length of the item
number OffsetDiffTime
if the offset of the item-take has changed, this is the difference;
  positive, the offset has been changed towards the start of the project
  negative, the offset has been changed towards the end of the project
  0, no changes to the offset of the item-take
Note: this is the offset of the take underneath the mousecursor, which might not be the same size, as the MediaItem itself!
So changes to the offset maybe changes within the MediaItem or the start of the MediaItem!
This could be important, if you want to affect other items with rippling.

Parameters:
optional boolean exlude_mousecursorsize
false or nil, get the item underneath, when it can be affected by the mouse-cursor(dragging etc): when in doubt, use this
true, get the item underneath the mousecursor only, when mouse is strictly above the item,
      which means: this ignores the item when mouse is not above it, even if the mouse could affect the item
optional integer x
nil, use the current x-mouseposition; otherwise the x-position in pixels
optional integer y
nil, use the current y-mouseposition; otherwise the y-position in pixels


^ Reaper version 6.05 SWS version 2.10.0.1 JS version 0.963 Ultraschall version 4.1ActionsList_GetAllActions

Lua: integer num_found_actions, integer sectionID, string sectionName, table actions, table CmdIDs, table ToggleStates, table shortcuts = ultraschall.ActionsList_GetAllActions()

returns the all actions from the actionlist, when opened.

The order of the tables of found actions, ActionCommandIDs and ToggleStates is the same in all of the three tables. They also reflect the order of userselection in the ActionList itself from top to bottom of the ActionList.

returns -1 in case of an error


Returnvalues:
integer num_found_actions
the number of found actions; -1, if not opened
integer sectionID
the id of the section, from which the found actions are from
string sectionName
the name of the found section
table actions
the texts of the found actions as a handy table
table CmdIDs
the ActionCommandIDs of the found actions as a handy table; all of them are strings, even the numbers, but can be converted using Reaper's own function reaper.NamedCommandLookup
table ToggleStates
the current toggle-states of the found actions; 1, on; 0, off; -1, no such toggle state available
table shortcuts
the shortcuts of the action as a handy table; separated by ", "


^ Reaper version 6.05 SWS version 2.10.0.1 JS version 0.963 Ultraschall version 4.1ActionsList_GetSelectedActions

Lua: integer num_found_actions, integer sectionID, string sectionName, table selected_actions, table CmdIDs, table ToggleStates, table shortcuts = ultraschall.ActionsList_GetSelectedActions()

returns the selected entries from the actionlist, when opened.

The order of the tables of found actions, ActionCommandIDs and ToggleStates is the same in all of the three tables. They also reflect the order of userselection in the ActionList itself from top to bottom of the ActionList.

returns -1 in case of an error


Returnvalues:
integer num_found_actions
the number of selected actions; -1, if not opened
integer sectionID
the id of the section, from which the selected actions are from
string sectionName
the name of the selected section
table selected_actions
the texts of the found actions as a handy table
table CmdIDs
the ActionCommandIDs of the found actions as a handy table; all of them are strings, even the numbers, but can be converted using Reaper's own function reaper.NamedCommandLookup
table ToggleStates
the current toggle-states of the selected actions; 1, on; 0, off; -1, no such toggle state available
table shortcuts
the shortcuts of the action as a handy table; separated by ", "


^ Reaper version 5.40 Ultraschall version 4.00CheckActionCommandIDFormat

Lua: boolean retval = ultraschall.CheckActionCommandIDFormat(action_command_id)

Checks, whether an action command id is a valid commandid(which is a number) or a valid _action_command_id (which is a string with an _underscore in the beginning).

Does not check, whether this action_command_id is a useable one, only if it's "syntax" is correct!

returns falsein case of an error

Returnvalues:
boolean retval
true, valid action_command_id; false, not a valid action_command_id

Parameters:
actioncommand_id
the ActionCommandID you want to check; either a number or an action_command_id with an underscore at the beginning


^ Reaper version 5.40 Ultraschall version 4.00CheckActionCommandIDFormat

Lua: boolean retval = ultraschall.CheckActionCommandIDFormat(action_command_id)

Checks, whether an action command id is a valid commandid(which is a number) or a valid _action_command_id (which is a string with an _underscore in the beginning).

Does not check, whether this action_command_id is a useable one, only if it's "syntax" is correct!

returns falsein case of an error

Returnvalues:
boolean retval
true, valid action_command_id; false, not a valid action_command_id

Parameters:
actioncommand_id
the ActionCommandID you want to check; either a number or an action_command_id with an underscore at the beginning


^ Reaper version 5.40 Ultraschall version 4.00CheckActionCommandIDFormat2

Lua: boolean retval = ultraschall.CheckActionCommandIDFormat2(action_command_id)

Checks, whether an action command id is a valid commandid(which is a number) or a valid _action_command_id (which is a string with an _underscore in the beginning).

Unlike CheckActionCommandIDFormat, this checks whether an action-command-id-string is an actual registered one(case sensitive!).

returns false in case of an error

Returnvalues:
boolean retval
true, valid action_command_id; false, not a valid action_command_id

Parameters:
actioncommand_id
the ActionCommandID you want to check; either a number or an action_command_id with an underscore at the beginning


^ Reaper version 5.977 SWS version 2.10.0.1 Ultraschall version 4.00GetAllActions

Lua: integer number_of_actions, table actiontable = ultraschall.GetAllActions(integer section)

Returns all actions and accompanying attributes from a specific section as a handy table

The table is of the following format:

    actiontable[index]["commandid"]       - the command-id-number of the action  
    actiontable[index]["actioncommandid"] - the action-command-id-string of the action, if it's a named 
                                            command(usually scripts or extensions), otherwise empty string  
    actiontable[index]["name"]            - the name of command  
    actiontable[index]["scriptfilename"]  - the filename+path of a command, that is a ReaScript, otherwise empty string  
    actiontable[index]["termination"]     - the termination-state of the action  
                                              -1  - not available  
                                              4   - Dialogwindow appears(Terminate, New Instance, Abort), if another 
                                                    instance of a given script is started, that's already running  
                                              260 - always Terminate All(!) Instances, if you try to run another 
                                                    instance of a script, that's already running. When no instance is 
                                                    running, it simply starts the script.  
                                              516 - always start a New Instance of the script, that's already running  
    actiontable[index]["consolidate"]     - the consolidate-state of custom actions; 
                                                1 consolidate undo points, 
                                                2 show in Actions-Menu, 
                                                3 consolidate undo points AND show in Actions Menu
                                                -1, if not available  
    actiontable[index]["actiontype"]      - the type of the action; 
                                            "native action", "extension action", 
                                            "custom action", "script"  

returns -1 in case of an error.


Returnvalues:
integer number_of_actions
the number of actions found; -1 in case of an error
table actiontable
a table, which holds all attributes of an action(see description for more details)

Parameters:
integer sections
the section, whose actions you want to retrieve
0, Main=0
1, invisible actions(shown but not runnable actions)
100, Main (alt recording)
32060, MIDI Editor=32060
32061, MIDI Event List Editor
32062, MIDI Inline Editor
32063, Media Explorer=32063


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetScriptFilenameFromActionCommandID

Lua: string scriptfilename_with_path = ultraschall.GetScriptFilenameFromActionCommandID(string action_command_id)

returns the filename with path of a script, associated to a ReaScript.
Command-ID-numbers do not work!
                        
returns false in case of an error

Returnvalues:
string scriptfilename_with_path
the scriptfilename with path associated with this ActionCommandID

Parameters:
string Path
the path to set as new current working directory


^ Reaper version 5.40 Ultraschall version 4.00RefreshToolbar_Action

Lua: ultraschall.RefreshToolbar_Action(integer section, string actioncommand_id)

Refreshes a toolbarbutton with an ActionCommandID(instead of the CommandID-number)

returns -1 in case of error

Parameters:
integer section
section
0 - Main
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
string actioncommand_id
ActionCommandID of the action, associated with the toolbarbutton


^ Reaper version 5.40 Ultraschall version 4.00RunCommand

Lua: integer retval = ultraschall.RunCommand(string actioncommand_id)

runs a command by its ActionCommandID(instead of the CommandID-number)

returns -1 in case of error

Returnvalues:
integer retval
-1, in case of error

Parameters:
string actioncommand_id
the ActionCommandID of the Command/Script/Action you want to run; must be either a number or the ActionCommandID beginning with an underscore _


^ Reaper version 5.40 Ultraschall version 4.00ToggleStateAction

Lua: integer retval = ultraschall.ToggleStateAction(integer section, string actioncommand_id, integer state)

Toggles state of an action using the actioncommand_id(instead of the CommandID-number)

returns current state of the action after toggling or -1 in case of error.

Returnvalues:
integer retval
state if the action, after it has been toggled

Parameters:
integer section
the section of the action(see ShowActionlist-dialog)
0 - Main
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
string actioncommand_id
the ActionCommandID of the action to toggle
integer state
toggle-state
0, off
&1, on/checked in menus
&2, on/grayed out in menus
&16, on/bullet in front of the entry in menus
-1, NA because the action does not have on/off states.


^ Reaper version 5.40 Ultraschall version 4.00ToggleStateButton

Lua: boolean retval = ultraschall.ToggleStateButton(integer section, string actioncommand_id, integer state)

Toggles state and refreshes the button of an actioncommand_id

returns false in case of error

Returnvalues:
boolean retval
true, toggling worked; false, toggling didn't work

Parameters:
integer section
the section of the action(see ShowActionlist-dialog)
0 - Main
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
string actioncommand_id
the ActionCommandID of the action to toggle
integer state
1 or 0


^ Reaper version 5.975 Ultraschall version 4.1Benchmark_GetAllStartTimesAndSlots

Lua: number starttime = ultraschall.Benchmark_GetStartTime()

This function is for benchmarking parts of your code. It returns a table with all starttimes of all current benchmark-measurings. The index of the table reflects the slots.

Use Benchmark_MeasureTime to start/reset a new benchmark-measureing.


Returnvalues:
table starttime_slots
a table with all starttimes of all current benchmark-measurings, where the index reflects the slots


^ Reaper version 5.975 Ultraschall version 4.1Benchmark_GetStartTime

Lua: number starttime = ultraschall.Benchmark_GetStartTime(optional integer slot)

This function is for benchmarking parts of your code. It returns the starttime of the last benchmark-start.

returns nil, if no benchmark has been made yet.

Use Benchmark_MeasureTime to start/reset a new benchmark-measureing.


Returnvalues:
number starttime
the starttime of the currently running benchmark

Parameters:
optional integer slot
the slot, whose starttime you want to get


^ Reaper version 5.975 Ultraschall version 4.1Benchmark_MeasureTime

Lua: number elapsed_time, string elapsed_time_string, string measure_evaluation = ultraschall.Benchmark_MeasureTime(optional integer time_mode, optional boolean reset, optional integer slot)

This function is for benchmarking parts of your code. It returns the passed time, since last time calling this function.

Use Benchmark_GetStartTime to start the benchmark.


Returnvalues:
number elapsed_time
the elapsed time in seconds
string elapsed_time_string
the elapsed time, formatted by parameter time_mode
string measure_evaluation
an evaluation of time, mostly starting with < or > an a number of +
0, no time passed
>, for elapsed times greater than 1, the following + will show the number of integer digits; example: 12.927 -> ">++"
<, for elapsed times smaller than 1, the following + will show the number of zeros+1 in the fraction, until the first non-zero-digit appears; example: 0.0063 -> "<+++"

Parameters:
optional integer time_mode
the formatting of elapsed_time_string
0=time
1=measures.beats + time
2=measures.beats
3=seconds
4=samples
5=h:m:s:f
optional boolean reset
true, resets the starttime(for new measuring); false, keeps current measure-starttime(for continuing measuring)
optional integer slot
if you want to have multiple benchmark-measures at the same time, you can store them in different slots.
means, you can measure in slot 1 and slot 2, where you can occasionally reset slot 1 while
having continuous measuring in slot 2.
this allows you to measure the execution time of the whole script(slot 2) and certain parts of the script
on individual basis(slot 1).
you can use as many slots, as you want.
nil, default slot is 0


^ Reaper version 5.965 Ultraschall version 4.00GetScriptIdentifier

Lua: string script_identifier = ultraschall.GetScriptIdentifier()

The Ultraschall-API gives any script, that uses the API, a unique identifier generated when the script is run. This identifier can be used to communicate with this script. If you start numerous instances of a script, it will create for each instance its own script-identifier, so you can be sure, that you communicate with the right instance.

The identifier is of the format "ScriptIdentifier:scriptfilename-{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}.ext", where the {}-part is a guid and ext either .lua .py or .eel

Defer1 to Defer20 make use of this to stop a running defer-loop from the outside of a deferred-script.


Returnvalues:
string script_identifier
a unique script-identifier for this script-instance, of the format:
ScriptIdentifier: scriptfilename-guid


^ Reaper version 5.965 Ultraschall version 4.00GetScriptIdentifier_Description

Lua: string script_identifier_description = ultraschall.GetScriptIdentifier_Description()

The Ultraschall-API gives any script, that uses the API, a unique identifier generated when the script is run. This identifier can be used to communicate with this script. If you start numerous instances of a script, it will create for each instance its own script-identifier, so you can be sure, that you communicate with the right instance.

With this function, you can get its description, that is less cryptic than the ScriptIdentifier itself.

You can set it using SetScriptIdentifier_Description.


Returnvalues:
string script_identifier_description
the description of your script


^ Reaper version 5.965 Ultraschall version 4.00GetScriptIdentifier_Title

Lua: string script_identifier_title = ultraschall.GetScriptIdentifier_Title()

The Ultraschall-API gives any script, that uses the API, a unique identifier generated when the script is run. This identifier can be used to communicate with this script. If you start numerous instances of a script, it will create for each instance its own script-identifier, so you can be sure, that you communicate with the right instance.

With this function, you can get its description, that is less cryptic than the ScriptIdentifier itself.

Default is the script's filename.

You can set it using SetScriptIdentifier_Title.


Returnvalues:
string script_identifier_title
the title of your script; default is the filename of the script


^ Reaper version 5.965 Ultraschall version 4.00GetScriptParameters

Lua: integer num_params, array params, string caller_script_identifier = ultraschall.GetScriptParameters(optional string script_identifier, optional boolean remove)

Gets the parameters stored for a specific script_identifier.

returns -1 in case of an error


Returnvalues:
integer num_params
the number of parameters available
array params
the values of the parameters as an array
string caller_script_identifier
the scriptidentifier of the script, that set the parameters

Parameters:
optional string script_identifier
the script-identifier, whose parameters you want to retrieve;
use nil, to get the parameters stored for the current script
optional boolean remove
true or nil, remove the stored parameter-extstates; false, keep them for later retrieval


^ Reaper version 5.965 Ultraschall version 4.00GetScriptReturnvalues

Lua: integer num_params, array retvals = ultraschall.GetScriptReturnvalues(string sender_script_identifier, optional boolean remove)

Gets the return-values which a specific sender_script_identifier sent to the current script.

If you have started numerous child-scripts and want to know, which child-script sent you return-values, see GetScriptReturnvalues_Sender

returns -1 in case of an error


Returnvalues:
integer num_retvals
the number of return-values available
array params
the values of the return-values as an array

Parameters:
string sender_script_identifier
the script-identifier, that sent the return-values to your script
optional boolean remove
true or nil, remove the stored retval-extstates; false, keep them for later retrieval


^ Reaper version 5.965 Ultraschall version 4.00GetScriptReturnvalues_Sender

Lua: integer count, array retval_sender = ultraschall.GetScriptReturnvalues_Sender()

Retrieves, which scripts sent returnvalues to the current script.


Returnvalues:
integer count
the number of scripts, who have left returnvalues for the current script
array retval_sender
the ScriptIdentifier of the scripts, who returned values


^ Reaper version 5.965 JS version 0.962 Ultraschall version 4.00MIDI_OnCommandByFilename

Lua: boolean retval, string script_identifier = ultraschall.MIDI_OnCommandByFilename(string filename, optional HWND Midi_EditorHWND, string ...)

Runs a command by a filename in the MIDI-editor-context. It internally registers the file temporarily as command, runs it and unregisters it again. This is especially helpful, when you want to run a command for sure without possible command-id-number-problems.

It returns a unique script-identifier for this script, which can be used to communicate with this script-instance. The started script gets its script-identifier using GetScriptIdentifier. You can use this script-identifier e.g. as extstate.

Returns false in case of an error


Returnvalues:
boolean retval
true, if running it was successful; false, if not
string script_identifier
a unique script-identifier, which can be used as extstate to communicate with the started scriptinstance

Parameters:
HWND Midi_EditorHWND
the window-handler of the MIDI-editor, in which to run the script; nil, for the last active MIDI-editor
string filename
the name plus path of the scriptfile to run
string ...
parameters, that shall be passed over to the script


^ Reaper version 5.95 Ultraschall version 4.00Main_OnCommandByFilename

Lua: boolean retval, string script_identifier = ultraschall.Main_OnCommandByFilename(string filename, string ...)

Runs a command by a filename. It internally registers the file temporarily as command, runs it and unregisters it again. This is especially helpful, when you want to run a command for sure without possible command-id-number-problems.

It returns a unique script-identifier for this script, which can be used to communicate with this script-instance. The started script gets its script-identifier using GetScriptIdentifier. You can use this script-identifier e.g. as extstate.

Returns false in case of an error


Returnvalues:
boolean retval
true, if running it was successful; false, if not
string script_identifier
a unique script-identifier, which can be used as extstate to communicate with the started scriptinstance

Parameters:
string filename
the name and path of the scriptfile to run
string ...
parameters that shall be passed over to the script


^ Reaper version 5.95 Ultraschall version 4.00Main_OnCommand_LuaCode

Lua: boolean retval, string script_identifier = ultraschall.Main_OnCommand_LuaCode(string Code, string ...)

Runs LuaCode as new temporary script-instance. It internally registers the code as a file temporarily as command, runs it and unregisters it again. This is especially helpful, when you want to run a command for sure without possible command-id-number-problems.

It returns a unique script-identifier for this script, which can be used to communicate with this script-instance. The started script gets its script-identifier using GetScriptIdentifier. You can use this script-identifier e.g. as extstate.

Returns false in case of an error


Returnvalues:
boolean retval
true, if running it was successful; false, if not
string script_identifier
a unique script-identifier, which can be used as extstate to communicate with the started code

Parameters:
string Code
the Lua-code, which shall be run; will not be checked vor validity!
string ...
parameters that shall be passed over to the script


^ Reaper version 5.965 Ultraschall version 4.00SetScriptIdentifier_Description

Lua: integer retval = ultraschall.SetScriptIdentifier_Description(string description)

The Ultraschall-API gives any script, that uses the API, a unique identifier generated when the script is run. This identifier can be used to communicate with this script. If you start numerous instances of a script, it will create for each instance its own script-identifier, so you can be sure, that you communicate with the right instance.

With this function, you can set its description, that is less cryptic than the ScriptIdentifier itself.

You can get it using GetScriptIdentifier_Description.

returns -1 in case of an error


Returnvalues:
integer retval
-1 in case of an error

Parameters:
string description
the new description of your script


^ Reaper version 5.965 Ultraschall version 4.00SetScriptIdentifier_Title

Lua: integer retval = ultraschall.SetScriptIdentifier_Title(string title)

The Ultraschall-API gives any script, that uses the API, a unique identifier generated when the script is run. This identifier can be used to communicate with this script. If you start numerous instances of a script, it will create for each instance its own script-identifier, so you can be sure, that you communicate with the right instance.

With this function, you can set its title, that is less cryptic than the ScriptIdentifier itself. No \n-newlines, \r-carriage returns or \0-nullbytes are allowed and will be removed

You can get it using GetScriptIdentifier_Title.

returns -1 in case of an error


Returnvalues:
integer retval
-1 in case of an error

Parameters:
string title
the new title of your script


^ Reaper version 5.965 Ultraschall version 4.00SetScriptParameters

Lua: boolean retval, string script_identifier = ultraschall.SetScriptParameters(string script_identifier, string ...)

Sets the parameters stored for a specific script_identifier.


Returnvalues:
boolean retval
true, storing was successful
string script_identifier
the script_identifier, whose parameters have been set

Parameters:
string script_identifier
the script-identifier, whose parameters you want to retrieve;
use nil, to set the parameters stored for the current script
string ...
the parameters you want to set; there can be more than one, but they must be strings


^ Reaper version 5.965 Ultraschall version 4.00SetScriptReturnvalues

Lua: boolean retval = ultraschall.SetScriptReturnvalues(string script_identifier, string ...)

Send return-values back to the script, that has a specific script_identifier.

returns false in case of an error


Returnvalues:
boolean retval
true, storing was successful; false, there was an error

Parameters:
string script_identifier
the script-identifier of the script-instance, to where you want to send the returnvalues
string ...
the returnvalues you want to set; there can be more than one, but they must be strings


^ Reaper version 5.965 SWS version 2.9.7 Ultraschall version 4.00GetSetIntConfigVar

Lua: boolean retval, integer config_var_value = ultraschall.GetSetIntConfigVar(string varname, boolean set, optional boolean bit1, ..., optional boolean bit32)

Gets/Sets an integer-bitfield of an integer-configvariable.

Pass to it a varname, if it shall be set or gotten from and up to 32 parameters who specify, if that bit shall be set(true) or not(false) or the currently set value shall be used(nil)

See Reaper_Config_Variables.html for more details on config-variables in Reaper.

returns false in case of an error

Returnvalues:
boolean retval
true, getting/setting the config-var was successful; false, it wasn't successful
integer config_var_value
the new/current value of the configuration-variable

Parameters:
string varname
the name of the config-variable
boolean set
true, set this config-var; false, don't set it
optional boolean bit1
true, set this bit; false, don't set this bit; nil, use the currently set value
...
true, set this bit; false, don't set this bit; nil, use the currently set value
optional boolean bit32
true, set this bit; false, don't set this bit; nil, use the currently set value


^ Reaper version 5.40 SWS version 2.9.7 Ultraschall version 4.00SetIntConfigVar_Bitfield

Lua: boolean retval, integer new_integer_bitfield = ultraschall.SetIntConfigVar_Bitfield(string configvar, boolean set_to, integer bit_1, integer bit_2, ... integer bit_n)

Alters an integer-bitfield stored by a ConfigVariable.

Returns false in case of error, like invalid bit-values, etc

Returnvalues:
boolean retval
true, if altering was successful; false, if not successful
integer new_integer_bitfield
the newly altered bitfield

Parameters:
string configvar
the config-variable, that is stored as an integer-bitfield, that you want to alter.
boolean set_to
true, set the bits to 1; false, set the bits to 0; nil, toggle the bits
integer bit1..n
one or more parameters, that include the bitvalues toset/unset/toggle with 1 for the first bit; 2 for the second, 4 for the third, 8 for the fourth, etc


^ Reaper version 5.975 Ultraschall version 4.00FindPatternsInString

Lua: integer count_found_items, array found_items = ultraschall.FindPatternsInString(string SourceString, string pattern, boolean sort_after_finding)

Finds all occurrences of matching-patterns in a string. You can sort them optionally.

returns -1 in case of an error


Returnvalues:
integer count_found_items
the number of found items in the string; -1, in case of an error
array found_items
all occurrences found in the string as an array

Parameters:
string SourceString
the source-string to search for all occurences
string pattern
the matching-pattern, with which to search for in the string
boolean sort_after_finding
true, sorts the entries; false, doesn't sort the entries


^ Reaper version 5.77 Ultraschall version 4.00AddIntToChar

Lua: string new_character = ultraschall.AddIntToChar(string character, integer int)

Adds/subtracts int to/from the numeric representation of character. It will return the new character.
It will not(!) include "overflows" into the adding/subtraction. That said, if you want to add a value resulting in a character above ASCII-code 255, it will fail!

Returns nil in case of an error

Returnvalues:
string new_character
the new character, after parameter int has been added/subtracted from/to character

Parameters:
string character
the character, onto which you want to add/subtract parameter int; only single character allowed
integer int
the value, that you want to add to the numerical representation of parameter character


^ Reaper version 5.965 Ultraschall version 4.00Base64_Decoder

Lua: string decoded_string = ultraschall.Base64_Decoder(string source_string, optional integer base64_type)

Converts a Base64-encoded string into a normal string. Currently, only standard Base64-encoding is supported.

Returns nil in case of an error


Returnvalues:
string decoded_string
the decoded string

Parameters:
string source_string
the Base64-encoded string
optional integer base64_type
the Base64-decoding-style
nil or 0, for standard default Base64-encoding


^ Reaper version 5.965 Ultraschall version 4.00Base64_Encoder

Lua: string encoded_string = ultraschall.Base64_Encoder(string source_string, optional integer base64_type, optional integer remove_newlines, optional integer remove_tabs)

Converts a string into a Base64-Encoded string. Currently, only standard Base64-encoding is supported.

Returns nil in case of an error


Returnvalues:
string encoded_string
the encoded string

Parameters:
string source_string
the string that you want to convert into Base64
optional integer base64_type
the Base64-decoding-style
nil or 0, for standard default Base64-encoding
optional integer remove_newlines
1, removes \n-newlines(including \r-carriage return) from the string
2, replaces \n-newlines(including \r-carriage return) from the string with a single space
optional integer remove_tabs
1, removes \t-tabs from the string
2, replaces \t-tabs from the string with a single space


^ Reaper version 5.40 Ultraschall version 4.00CSV2IndividualLinesAsArray

Lua: integer count, array individual_values = ultraschall.CSV2IndividualLinesAsArray(string csv_line, optional string separator)

convert a csv-string to an array of the individual values. If separator cannot be found, it'll return the original string

returns nil in case or error

Returnvalues:
integer count
the number of entries
array individual_values
all values, each in an individual array-position

Parameters:
string csv_line
a string as a csv, with all values included and separated by parameter separator
string separator
the separator, that separates the individual entries; use nil for commas; separators will be removed from the final strings!


^ Reaper version 5.40 Ultraschall version 4.00CSV2Line

Lua: string values = ultraschall.CSV2Line(string csv_line)

converts a string of csv-values into a string with all values and without the ,-separators

returns nil in case of error

Returnvalues:
string values
all values in one string


^ Reaper version 5.95 Ultraschall version 4.00CombineBytesToInteger

Lua: integer retval = ultraschall.CombineBytesToInteger(integer bitoffset, integer Byte_1, optional Byte_2, ..., optional Byte_n)

Combines the Byte-values Byte_1 to Byte_n into one integer.
That means, if you give 4 values, it will return a 32bit-integer(4*8Bits).

Negative values will use the maximum possible value of that byte minus the bits.
In Byte_1, -2 will be 255-1=254, in Byte 2, -2 will be 65280-256=65024.

Use bitoffset to define, from which bit on you want to combine the values.

Returns -1 in case of an error

Returnvalues:
integer retval
the combined integer

Parameters:
integer bitoffset
if you want to start combining the values from a certain bitoffset-onwards, set the offset here; use 0 to start with the first bit.
integer Byte_1
a bytevalue that you want to combine into one
optional integer Byte_2
a bytevalue that you want to combine into one
optional integer Byte_n
a bytevalue that you want to combine into one


^ Reaper version 5.40 Ultraschall version 4.00CompareArrays

Lua: table diff_array = ultraschall.CompareArrays(table Array, table CompareArray2)

Compares Array using parameter CompareArray2 and returns an array with all entries in CompareArray2, that are not in Array.
The comparable arrays must be indexed by integer-numbers.

Returns nil in case of an error

Returnvalues:
table diff_array
an array with all entries from CompareArray2, that are not in Array

Parameters:
table Array
the reference-array
table CompareArray2
the array you want to check against Array; all entries in CompareArray2 that are not in Array will be returned


^ Reaper version 5.40 Ultraschall version 4.00CompareStringWithAsciiValues

Lua: boolean retval, integer errorposition = ultraschall.CompareStringWithAsciiValues(string string, integer bytevalue_1, integer bytevalue_2, ... integer bytevalue_n)

Compares a string with a number of byte-values(like ASCII-values).
Bytevalues can be either decimal and hexadecimal.
-1, if you want to skip checking of a specific position in string.

Returns false in case of error

Returnvalues:
boolean retval
true, if check was successful; false, if not successful
integer errorposition
if retval is false, this will contain the position in string, where the checking failed; nil, if retval is true

Parameters:
string string
the string to check against the bytevalues
integer bytevalue_1..n
one or more parameters, that include the bytevalues to check against the accompanying byte in string; -1, if you want to skip check for that position


^ Reaper version 5.95 Ultraschall version 4.00ConcatIntegerIndexedTables

Lua: integer numentries, array concatenated_table = ultraschall.ConcatIntegerIndexedTables(array table1, array table2)

Concatenates the entries of two tables into one table. The entries of each table must be indexed by integers

The new table still has the same references as the old table, means: if you remove the old tables/entries in the old tables, the concatenated table/accompanying entries will loose elements. To get a "true"-concatenated copy, you should first create new copies of the tables, using MakeCopyOfTable.


Returnvalues:
integer numentries
the number of entries in the new table
array concatenated_table
the new concatenated table

Parameters:
array table1
the first table to be concatenated; the entries must be indexed by integer-numbers!
array table2
the second table to be concatenated; the entries must be indexed by integer-numbers!


^ Reaper version 5.977 Ultraschall version 4.00ConvertAscii2Hex

Lua: string hexstring = ultraschall.ConvertAscii2Hex(string ascii_string)

converts an ascii-string into a hexstring.

See ConvertHex2Ascii to convert a HEX-string into its normal string-representation.

Returns nil in case of an error


Returnvalues:
string hexstring
the original string with only hexadecimal numbers

Parameters:
string ascii_string
the converted string


^ Reaper version 5.965 Ultraschall version 4.00ConvertBitsToInteger

Lua: integer integervalue = ultraschall.ConvertBitsToInteger(table bitvalues)

converts a table with all bitvalues into it's integer-representation.
each table-entry holds either a 1 or a 0;
  with index 1 being the first (for 1),
  index 2 for the second (for 2),
  index 3 for the third (for 4),
  index 4 for the fourth(for 8), etc

returns nil in case of an error

Returnvalues:
integer integer
the integer-number converted from the integer-entries

Parameters:
table bitvalues
a table, where each entry contains the bit-value of integer; first entry for bit 1, 64th entry for bit 64, etc


^ Reaper version 5.965 Ultraschall version 4.00ConvertBitsToString

Lua: string message = ultraschall.ConvertBitsToString(array bitarray)

converts a table of bit-representation into a string

Every entry in the table must be either 0 or 1. If there are too few bits to fill up a byte, the missing bits will be seen as trailing 0-bits.

returns nil in case of an error

Returnvalues:
string message
the converted bits as string-representation

Parameters:
array bitarray
the individual bits in a table, which will be converted into a string-representation
each entry in the table must be either 0 or 1; missing bits at the end(usually nil) will be seen as 0


^ Reaper version 5.977 Ultraschall version 4.00ConvertHex2Ascii

Lua: string ascii_string = ultraschall.ConvertHex2Ascii(string hexstring)

converts a hexstring into an ascii-string.

Will combine two hexvalues into one byte, until the whole string is converted.

See ConvertAscii2Hex to convert a string into its HEX-representation.

Returns nil in case of an error


Returnvalues:
string ascii_string
the converted string

Parameters:
string hexstring
the original string with only hexadecimal numbers


^ Reaper version 5.965 Ultraschall version 4.00ConvertIntegerIntoString2

Lua: string converted_value = ultraschall.ConvertIntegerIntoString2(integer Size, integer integervalue_1, ..., integer integervalue_n)

Splits numerous integers into its individual bytes and converts them into a string-representation.
Maximum 32bit-integers are supported.

Returns nil in case of an error.

Returnvalues:
string converted_value
the string-representation of the integer

Parameters:
integer Size
the maximum size of the integer to convert, 1(8 bit) to 4(32 bit)
integer integervalue_1
the first integer value to convert from
...
integer integervalue_n
the last integer value to convert from


^ Reaper version 5.965 Ultraschall version 4.00ConvertIntegerToBits

Lua: string bitvals_csv, table bitvalues = ultraschall.ConvertIntegerToBits(integer integer)

converts an integer-value(up to 64 bits) into it's individual bits and returns it as comma-separated csv-string as well as a table with 64 entries.

returns nil in case of an error

Returnvalues:
string bitvals_csv
a comma-separated csv-string of all bitvalues, with bit 1 coming first and bit 32 coming last
table bitvalues
a 64-entry table, where each entry contains the bit-value of integer; first entry for bit 1, 64th entry for bit 64

Parameters:
integer integer
the integer-number to separated into it's individual bits


^ Reaper version 5.40 Ultraschall version 4.00ConvertStringToAscii_Array

Lua: integer length, table byte_array = ultraschall.ConvertStringToAscii_Array(string string)

Converts a string into it's individual characters and numerical-representation as a table and after that returns its number of table-entries and the table.

Returns -1 if string isn't a valid string

Returnvalues:
integer length
the number of characters in the string/entries in the returned table byte_array
table byte_array
the ByteArray as a table, with the format
    ByteArray[idx][1]="A" -- the byte itself
    ByteArray[idx][2]=65  -- the numerical representation of the byte

Parameters:
string string
the string to be converted


^ Reaper version 5.965 Ultraschall version 4.00ConvertStringToBits

Lua: integer number_of_bits, array bitarray = ultraschall.ConvertStringToBits(string message)

converts a string into its bit-representation and returns that as a handy table

returns -1 in case of an error

Returnvalues:
integer number_of_bits
the number of bits in the string, -1, in case of an error
array bitarray
the individual bits as a handy table

Parameters:
string message
the string, which you want to convert into its bit representation


^ Reaper version 5.965 Ultraschall version 4.00ConvertStringToIntegers

Lua: integer num_integers, array individual_integers = ultraschall.ConvertStringToIntegers(string String, integer Size)

Converts a string into its integer-representation. Allows you to set the size of the integers between 1 Byte and 8 Bytes(64 bits).

Returns -1 in case of an error.

Returnvalues:
integer num_integers
the number of integers converted from this string
array individual_integers
the individual integers, as converted from the original string

Parameters:
string String
the string to convert into its integer representation
integer Size
the size of the integers. 1 for 8 bits, 2 for 16 bits, ..., 8 for 64 bits


^ Reaper version 5.40 Ultraschall version 4.00CountCharacterInString

Lua: integer count, array positions = ultraschall.CountCharacterInString(string checkstring, string character)

Counts, how often character appears in checkstring and returns the count, as well as a array an with the position-numbers.

returns -1 in case of error

Returnvalues:
integer count
the number of occurences of character in checkstring
array positions
the positionnumbers of the character in checkstring

Parameters:
string checkstring
the string to check search through
string character
the character to search for. Only single characters are allowed. Controlcodes like \n \t count as single character. Case sensitive.


^ Reaper version 5.40 Ultraschall version 4.00CountEntriesInTable_Main

Lua: integer count, table subtables, integer count_of_subtables = ultraschall.CountEntriesInTable_Main(table the_table)

Counts the number of entries in an indexed table.
Will only count the entries from the main-table, not it's subtables. If you want to know the number of subtables, this function returns a table that includes all subtables found in the main-table,
as well as the number of found subtables.

Returns -1 if table isn't a valid table

Returnvalues:
integer count
the number of entries in the table
table subtables
if an entry of table has a table as value, that table-value will be included in this subtables-table(for recursive counting-usecases)
integer count_of_subtables
the number of entries in the subtables-table

Parameters:
table table
the table, whose entries you want to count


^ Reaper version 5.77 Ultraschall version 4.00CountLinesInString

Lua: integer number_of_lines = ultraschall.CountLinesInString(string String)

Counts the lines in a string. It counts them by counting \n-newlines(not carriage returns!)

Returns -1 in case of an error

Returnvalues:
integer number_of_lines
number of lines of the string

Parameters:
string String
the string to count the lines of


^ Reaper version 5.52 Ultraschall version 4.00CountPatternInString

Lua: integer count, array positions = ultraschall.CountPatternInString(string sourcestring, string searchstring, boolean non_case_sensitive)

returns the count and an array with all positions of searchstring in sourcestring.

Returnvalues:
integer count
the number of appearances of searchstring in sourcestring
array positions
an array with count-entries, where every entry contains the position of searchstring in sourcestring

Parameters:
string sourcestring
the string, you want to search through
string searchstring
the string, you want to search for in sourcestring
boolean non_case_sensitive
true, the search does not care about case-sensitivity; false, case of searchstring will be kept


^ Reaper version 5.95 Ultraschall version 4.00CycleTable

Lua: table new_table = ultraschall.CycleTable(table the_table, integer offset)

Cycles the entries by offset. Offset can be positive(cycle forward) or negative(cycle negative). The number also tells the function, by how many entries the table shall be cycled, with 1 for one entry, 2 for 2 entries, etc.
Entries "falling out" of one side(top or bottom) of the table will be readded on the other side.

returns nil in case of error

Returnvalues:
table new_table
the altered table

Parameters:
table the_table
the table to cycle through
integer offset
the offset, by which to cycle the entries through; positive, cycle entries forward; negative, cycle entries backward


^ Reaper version 5.965 Ultraschall version 4.00DB2MKVOL

Lua: number mkvol_value = ultraschall.DB2MKVOL(number db_value)

Converts an dB-value into a MKVOL-value.

MKVOL-values are used by the routing-functions for HWOut/AUXSendReceive, specifically for their volume-value as these can't be converted using Reaper's own DB2SLIDER or SLIDER2DB, so this function should help you.

See MKVOL2DB to convert a MKVOL-value into it's dB-representation

returns nil in case of an error


Returnvalues:
number mkvol_value
the mkvol-value, converted from the dB-value

Parameters:
number db_value
the dB-value, that you want to convert into the MKVOL-value; minimum is -144dB


^ Reaper version 6.05 Ultraschall version 4.1EscapeMagicCharacters_String

Lua: string escaped_string = ultraschall.EscapeMagicCharacters_String(string sourcestring)

Escapes the magic characters(needed for pattern matching), so the string can be fed as is into string.match-functions.
    That way, characters like . or - or * etc do not trigger pattern-matching behavior but are used as regular . or - or * etc.

returns nil in case of an error

Returnvalues:
string escaped_string
the string with all magic characters escaped

Parameters:
string sourcestring
the string, whose magic characters you want to escape for future use


^ Reaper version 5.77 Ultraschall version 4.00GetAllEntriesFromTable

Lua: integer count, table foundtypes, table returned_table = ultraschall.GetAllEntriesFromTable(table table)

Gets an iterable version of table. Good for analysing unknown tables.

Returns the number of entries, a table(array) with the datatypes of each entry and the table with all it's entries in the same order as in the foundtypes-table.

This doesn't treat table recursivley, means: each "Subtable" within the table is treated as one entry of the type "table". That means, that these tables must be analysed themselves in an extra step!
A[1]=1
A[2][1]=2
A[2][2]=3.4
will return two(!) entries, the first being of type "integer", the second being of type "table". Next step would be to run use this function to analyse A[2] as well, which would result in two entries: the first being of type "integer" and the second of type "float", etc.

returns -1 in case of error

Returnvalues:
integer count
the number of table-entries found
table foundtypes
a table, with count-entries, each entry having the type of each entry in the returned_table as string.
The types can be "nil", "integer", "float", "string", "boolean", "table", "function", "thread", "userdata"
table returned_table
an iterable version of table. The type of each entry can be found in the accompanying entry of foundtypes
the format is returned_table[indexnr][1] - indexname/number of the original table-entry
              returned_table[indexnr][2] - the value of the original table-entry
the indexnr is 1 to count, while [indexnr][1] is the indexnr of the original-table-entry, which might be a string, functionname or something else as well

Parameters:
table table
the table to get the individual entries from


^ Reaper version 5.95 Ultraschall version 4.00GetDuplicatesFromArrays

Lua: integer duplicate_count, array duplicate_array, integer originalscount_array1, array originals_array1, integer originalscount_array2, array originals_array2 = ultraschall.GetDuplicatesFromArrays(array array1, array array2)

Returns the duplicates and the originals(entries only in one of the arrays) of two arrays. It will also return the number of entries.

This works only on arrays with integer-indexed entries; index must start with index 1!

returns -1 in case of an error

Returnvalues:
integer duplicate_count
the number of entries in both arrays
array duplicate_array
the entries in both arrays
integer originalscount_array1
the number of entries only in array1
array originals_array1
the entries that are only existing in array1
integer originalscount_array2
the number of entries only in array2
array originals_array2
the entries that are only existing in array2

Parameters:
array array1
the first array to check for duplicates and "original"-entries
array array2
the second array to check for duplicates and "original"-entries


^ Reaper version 5.40 Ultraschall version 4.00GetPartialString

Lua: string partial_string = ultraschall.GetPartialString(string str, string sep1, string sep2)

returns the part of a filename-string between sep1 and sep2

returns nil if it doesn't work, no sep1 or sep2 exist

Returnvalues:
string partial_string
the partial string between sep1 and sep2

Parameters:
string str
string to be processed
string sep1
separator on the "left" side of the partial string
string sep2
separator on the "right" side of the partial string


^ Reaper version 5.77 Ultraschall version 4.1IsValidMatchingPattern

Lua: boolean retval = ultraschall.IsValidMatchingPattern(string patstring)

Returns, if patstring is a valid pattern-matching-string

Returnvalues:
boolean retval
true, patstring is a valid pattern-matching-string; false, patstring isn't a valid pattern-matching-string

Parameters:
string patstring
the string to check for, if it's a valid pattern-matching-string


^ Reaper version 5.40 Ultraschall version 4.00KeepTableEntriesOfType

Lua: table alteredtable = ultraschall.KeepTableEntriesOfType(table worktable, string keeptype)

Removes all entries from worktable, that are not of the datatype as given by keeptype.

returns nil in case of error

Returnvalues:
table alteredtable
the table, that contains only the entries of the type as given by parameter keeptype

Parameters:
table worktable
the unaltered source-table for processing
string keeptype
the type that shall remain in table
allowed are boolean, integer, float, number, table, string, userdata, thread, ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source


^ Reaper version 6.16 Ultraschall version 4.2LimitFractionOfFloat

Lua: number altered_number = ultraschall.LimitFractionOfFloat(number number, integer length_of_fraction)

limits the fraction of a float-number to a specific length of fraction(digits). You can also choose to round the value or not.

returns nil in case of error

Returnvalues:
number altered_number
the altered number with the new fraction-length. Will be equal to parameter number, if number was integer or fraction less digits than length_of_fraction

Parameters:
number number
the number, whose fraction shall be limited
integer length_of_fraction
the number of digits in the fraction


^ Reaper version 5.965 Ultraschall version 4.00MKVOL2DB

Lua: number db_value = ultraschall.MKVOL2DB(number mkvol_value)

Converts an MKVOL-value into a dB-value.

MKVOL-values are used by the routing-functions for HWOut/AUXSendReceive, specifically for their volume-value as these can't be converted using Reaper's own DB2SLIDER or SLIDER2DB, so this function should help you.

This function is an adapted one from the function provided in Plugins/reaper_www_root/main.js

See DB2MKVOL to convert a dB-value into it's MKVOL-representation

returns nil in case of an error


Returnvalues:
number db_value
the dB-value, converted from the MKVOL-value; minimum -144dB

Parameters:
number mkvol_value
the mkvol_value, that you want to convert into dB


^ Reaper version 5.40 Ultraschall version 4.00MakeCopyOfTable

Lua: table table_copy = ultraschall.MakeCopyOfTable(table table)

Creates a true copy of a table(not only references).

adapted from Tyler Neylon's function, found at Stack Overflow

Returns nil if table isn't a valid table


Returnvalues:
table table_copy
the true copy of the table; nil in case of error

Parameters:
table table
the table to create a copy from.


^ Reaper version 5.40 Ultraschall version 4.00Notes2CSV

Lua: string csv_retval = ultraschall.Notes2CSV()

Gets the project's notes and returns it as a CSV.

Returnvalues:
string csv_retval
the project notes, returned as a csv-string; entries separated by a comma


^ Reaper version 5.40 Ultraschall version 4.00RemoveTableEntriesOfType

Lua: table alteredtable = ultraschall.RemoveTableEntriesOfType(table worktable, string removetype)

Removes all entries from worktable, that are of the datatype as given by removetype.

returns nil in case of error

Returnvalues:
table alteredtable
the table, that contains only the entries that are nt of the type as given by parameter removetype

Parameters:
table worktable
the unaltered source-table for processing
string removetype
the type that shall be removed from table
allowed are boolean, integer, float, number, table, string, userdata, ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source


^ Reaper version 5.965 Ultraschall version 4.00ReplacePartOfString

Lua: string replaced_string = ultraschall.ReplacePartOfString(string originalstring, string insertstring, integer offset, optional integer length)

replaces a part of a string with a second string

Returns nil in case of an error

Returnvalues:
string replaced_string
the altered string

Parameters:
string originalstring
the originalstring, in which you want to insert the string
string insertstring
the string that shall be inserted
integer offset
the position, at which to insert the string; it is the position BEFORE the position at which to insert, so if you want to replace the 25th character, offset is 24!
optional integer length
the length of the part of the originalstring that shall be replaced, counted from offset. 0 or nil for simple insertion.


^ Reaper version 5.982 Ultraschall version 4.00ReplacePatternInString

Lua: string altered_string, boolean replaced = ultraschall.ReplacePatternInString(string OriginalString, string pattern, string replacestring, integer index)

Replaces the index'th occurrence of pattern in OriginalString with replacepattern.

Unlike string.gsub, this replaces only the selected pattern!

returns nil, false in case of an error


Returnvalues:
string altered_string
the altered string, where the n'th occurence of the pattern has been replaced
boolean replaced
true, there has been a replacement; false, no replacement has happened

Parameters:
string OriginalString
the string, from which you want to replace a specific occurence of a matching pattern
string pattern
the pattern to look for
string replacestring
the string, which shall replace the found pattern
integer index
the number of found occurence of the pattern in the string, which shall be replaced


^ Reaper version 5.92 Ultraschall version 4.00ReturnTableAsIndividualValues

Lua: retval1, retval2, retval3, ... , retval64 = ultraschall.ReturnTableAsIndividualValues(table Table)

Returns the first 64 entries of an numerical-indexed table as returnvalues

Returnvalues:
retval1 ... retval64
the values from Table returned

Parameters:
table Table
the table, whose values you want to return. It will only return values with index 1...64!


^ Reaper version 5.965 Ultraschall version 4.00ReverseEndianess_Byte

Lua: integer newbyte = ultraschall.ReverseEndianess_Byte(integer byte)

reverses the endianess of a byte and returns this as value.
The parameter byte must be between 0 and 255!

returns nil in case of an error

Returnvalues:
integer newbyte
the endianess-reversed byte

Parameters:
integer byte
the integer whose endianess you want to reverse


^ Reaper version 5.40 Ultraschall version 4.00ReverseTable

Lua: table reversed_table, integer entry_count = ultraschall.ReverseTable(table the_table)

reversed the order of the entries of a table, means, the last entry will become the first, the first become the last, etc.
The table must be indexed by integers.

Returns nil if table isn't a valid table

Returnvalues:
table reversed_table
the resulting table with the reversed order of all entries
integer entry_count
the number of entries in the reversed_table

Parameters:
table table
the table, whose entries you want to reverse


^ Reaper version 5.40 Ultraschall version 4.00RoundNumber

Lua: integer retval = ultraschall.RoundNumber(number num)

returns a rounded value of the parameter number. %.5 and higher rounds up, lower than %.5 round down.

returns nil in case of an error

Returnvalues:
integer retval
the rounded number

Parameters:
number num
the floatingpoint number, you'd like to have rounded.


^ Reaper version 5.77 Ultraschall version 4.00SearchStringInString

Lua: integer count, array posarray = ultraschall.SearchStringInString(string fullstring, string searchstring)

Searches for the string searchstring in fullstring.

Keep in mind: Umlauts may produce multibyte-values. Therefore, the returned offsets might be confusing.

returns -1 in case of error, 0 if string wasn't found

Returnvalues:
integer count
the number of found occurences of searchstring in fullstring
array posarray
an array that contains the positions, where searchstring was found within fullstring

Parameters:
string fullstring
the string to be searched through
string searchstring
the string to search for within fullstring


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00SecondsToTime

Lua: string time_string = ultraschall.SecondsToTime(number pos)

converts timeposition in seconds(pos) to a timestring (h)hh:mm:ss.mss

returns nil in case of error

Returnvalues:
string time_string
timestring in (h)hh:mm:ss.mss

Parameters:
number pos
timeposition in seconds


^ Reaper version 5.40 Ultraschall version 4.00SecondsToTimeString_hh_mm_ss_mss

Lua: string timestring = ultraschall.SecondsToTimeString_hh_mm_ss_mss(number time)

Converts the parameter time into a timestring of the format hh:mm:ss.mss
Valid timeranges are from 0 to 359999.99 seconds(about 99 hours).

returns -1 in case of error

Returnvalues:
string timestring
the converted timestring. It will always follow the format hh:mm:ss.mss and fill up digits with zeros, if necessary.

Parameters:
number time
the time in seconds to be converted into the timestring


^ Reaper version 5.40 Ultraschall version 4.00SetBitfield

Lua: integer new_integer_bitfield = ultraschall.SetBitfield(integer integer_bitfield, boolean set_to, integer bit_1, integer bit_2, ... integer bit_n)

Alters an integer-bitfield.

Returns nil in case of error, like invalid bit-values

Returnvalues:
integer new_integer_bitfield
the newly altered bitfield

Parameters:
integer integer_bitfield
the old integer-bitfield that you want to alter
boolean set_to
true, set the bits to 1; false, set the bits to 0; nil, toggle the bits
integer bit1..n
one or more parameters, that include the bitvalues toset/unset/toggle with 1 for the first bit; 2 for the second, 4 for the third, 8 for the fourth, etc


^ Reaper version 5.95 Ultraschall version 4.00SplitIntegerIntoBytes

Lua: integer Byte1, integer Byte2, integer Byte3, integer Byte4 = ultraschall.SplitIntegerIntoBytes(integer integervalue)

Splits a 32-bit-integer-value into four bytes.

Returns -1 in case of an error

Returnvalues:
integer Byte1
the first eight bits of the integer-value as a Byte
integer Byte2
the second eight bits of the integer-value as a Byte
integer Byte3
the third eight bits of the integer-value as a Byte
integer Byte4
the fourth eight bits of the integer-value as a Byte

Parameters:
integer integeroffset
the integer-value that you want to split into individual bytes


^ Reaper version 5.40 Ultraschall version 4.00SplitStringAtLineFeedToArray

Lua: integer count, array split_string = ultraschall.SplitStringAtLineFeedToArray(string unsplitstring)

Splits the string unsplitstring at linefeed/tabs/control characters and puts each of these splitpieces into an array, each splitpiece one array-entry.
The linefeeds will not(!) be returned in the array's entries.
Returns the number of entries in the array, as well as the array itself
If there are no control characters or linefeeds in the string, the array will have only one entry with unsplitstring in it.
  
  returns -1 in case of failure

Returnvalues:
integer count
number of entries in the split_string-array
array split_string
an array with all the individual "postsplit"-pieces of the string

Parameters:
string unsplitstring
the string, that shall be split at LineFeed/Tabs/Control Characters. Nil is not allowed.


^ Reaper version 5.941 Ultraschall version 4.00SplitStringAtNULLBytes

Lua: integer count, array split_strings = ultraschall.SplitStringAtNULLBytes(string splitstring)

Splits splitstring into individual string at NULL-Bytes.

returns -1 in case of an error

Returnvalues:
integer count
the number of found strings
array split_strings
the found strings put into an array

Parameters:
string splitstring
the string with NULL-Bytes(\0) into it, that you want to split


^ Reaper version 5.965 Ultraschall version 4.00StateChunkLayouter

Lua: string layouted_statechunk = ultraschall.StateChunkLayouter(string statechunk)

Layouts StateChunks as returned by GetTrackStateChunk or GetItemStateChunk into a format that resembles the formatting-rules of an rpp-file.
This is very helpful, when parsing such a statechunk, as you can now use the number of spaces used for intendation as help parsing.
Usually, every new element, that starts with < will be followed by none or more lines, that have two spaces added in the beginning.
Example of a MediaItemStateChunk(I use . to display the needed spaces in the beginning of each line):

<ITEM
..POSITION 6.96537864205337
..SNAPOFFS 0
..LENGTH 1745.2745
..LOOP 0
..ALLTAKES 0
..FADEIN 1 0.01 0 1 0 0
..FADEOUT 1 0.01 0 1 0 0
..MUTE 0
..SEL 1
..IGUID {020E6372-97E6-4066-9010-B044F67F2772}
..IID 1
..NAME myaudio.flac
..VOLPAN 1 0 1 -1
..SOFFS 0
..PLAYRATE 1 1 0 -1 0 0.0025
..CHANMODE 0
..GUID {79F087CE-49E8-4212-91F5-8487FBCF10B1}
..<SOURCE FLAC
....FILE "C:\Users\IncredibleSupergirl\Desktop\X_audiofile.flac"
..>
>


This function will not check, if you've passed a valid statechunk!

returns nil in case of an error

Returnvalues:
string layouted_statechunk
the statechunk, that is now layouted to the rules of rpp-projectfiles

Parameters:
string statechunk
a statechunk, that you want to layout properly


^ Reaper version 5.40 Ultraschall version 4.00TimeStringToSeconds_hh_mm_ss_mss

Lua: number time = ultraschall.TimeStringToSeconds_hh_mm_ss_mss(string timestring)

Converts the parameter timestring of the format hh:mm:ss.mss into seconds
The timestring must follow strictly this format, or the function returns -1 as result.

returns -1 in case of error

Returnvalues:
number time
the time in seconds to be converted into the timestring, -1 in case of an error

Parameters:
string timestring
the converted timestring. It must always follow the format hh:mm:ss.mss. Fill up digits with zeros, if necessary.


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00TimeToSeconds

Lua: number position = ultraschall.TimeToSeconds(string timestring)

converts a timestring days:hours:minutes:seconds.milliseconds to timeposition in seconds
it is ok, to have only some of the last ones given, so i.e. excluding days and hours is ok. Though excluding values inbetween does not work!

A single integer in timestring will be seen as seconds.
To only specifiy milliseconds in particular, start the number with a .
all other values are separated by :

returns -1 in case of error, timestring is a nil or if you try to add an additional value, added before days

does not check for valid timeranges, so 61 minutes is possible to give, even if hours are present in the string

Returnvalues:
number position
the converted position

Parameters:
string timestring
a string like: days:hours:minutes:seconds.milliseconds , i.e. 1:16:27:50.098


^ Reaper version 6.02 Ultraschall version 4.00FloatCompare

Lua: boolean retval, number diff = ultraschall.FloatCompare(number a, number b, number precision)

Compares two floatvalues and allows to set the precision to copmare against.

So, if you want to compare 5.1 and 5.2, using precision=0.2 returns true(is equal), precision=0.1 returns false(isn't equal).

Returns nil in case of failure.

Returnvalues:
boolean retval
true, numbers are equal; false, numbers aren't equal
number diff
the difference between numbers a and b

Parameters:
number a
the first float-number to compare
number b
the second float-number to compare
number precision
the precision of the fraction, like 0.1 or 0.0063


^ Reaper version 5.40 Ultraschall version 4.00ReturnTypeOfReaperObject

Lua: string objecttype = ultraschall.ReturnTypeOfReaperObject(Reaperobject object)

returns the type of a Reaper-object.

Returnvalues:
string objecttype
the type of the parameter of object
the following types can be returned:
ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source, None

Parameters:
Reaperobject object
a Reaper-object of the following types:
ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source
returns None if the object isn't a valid Reaper-object


^ Reaper version 5.40 Ultraschall version 4.00toboolean

Lua: boolean retval = toboolean(string value)

Converts the string "value" to a boolean, if applicable; means: if it contains either true or false in it.
If it contains both or other characters(except spaces or tabs), it will not convert.
Works basially like Lua's own tostring() or tonumber()-functions.

Returns nil, if conversion isn't possible.

Note: Unlike other ultraschall-api-functions, toboolean() has no ultraschall. in it's functionname!

Returnvalues:
boolean retval
true or false, depending on the input variable value

Parameters:
string value
the value to be converted to a boolean. True and false can be upper-, lower and camelcase.


^ Reaper version 5.77 Ultraschall version 4.00type

Lua: string type_of_object, optional boolean isnumber = ultraschall.type(identifier object)

Returns the type of the object.
Supported types are Lua's own datatypes as well as Reaper's own datatypes.

Due API-limitations, SWS-specific datatypes are not supported in this function!

Returnvalues:
string type_of_object
the type of the object; the following are valid:
nil, number: integer, number: float, boolean, string, function, table, thread, userdata,
ReaProject, MediaItem, MediaItem_Take, MediaTrack, TrackEnvelope, AudioAccessor, joystick_device, PCM_source
userdata will be shown, if object isn't of any known type
optional boolean isnumber
true, if object is a number(either integer or number)

Parameters:
identifier object
the object, whose type you want to know


^ Reaper version 5.95 Ultraschall version 4.00PingMe

Lua: string pingmessage = PingMe(optional string message, optional integer outputtarget)

Shows the current script and line of script-execution, optionally with a message.

This is for debugging-purposes. For instance, if you want to know, if an if-statement is working as you expect it, just add
PingMe() into that if-statement.
It will show a message including linenumbers, when the if-statement is going through.

You can also choose, whether to output the message into ReaConsole, Messagebox or clipboard(including culminating options)

Returnvalues:
string pingmessage
returns the pingmessage

Parameters:
optional string message
an optional message shown
optional integer outputtarget
0, don't show a message
1, output the pingme-message into ReaScript-console
2 or nil, show a messagebox
3, output it into the clipboard
4, add it to the end of the contents of the clipboard
5, add it to the beginning of the contents of the clipboard


^ Reaper version 5.965 Ultraschall version 4.00deprecated

Lua: ultraschall.deprecated(string functionname)

If you have a 3rd-party function added to Ultraschall-API, which you want to deprecate, use this function to show a warning message, if that function is used.

It will be shown once when running the script, after (re-)start of Reaper.

That way, you can tell scripters, whether they need to update their scripts using newer/better functions. This is probably shown first to the user, who knows that way a potential problem and can tell the scripter about that.

If there is a line "Author: authorname" in the file(as usual for ReaPack-compatible scripts), it will show the scripter's name in the dialog.


Returnvalues:
boolean retval
true, defer-instance is running; false, defer-instance isn't running


^ Reaper version 5.975 Ultraschall version 4.00ConvertFunction_FromBase64String

Lua: function function = ultraschall.ConvertFunction_FromBase64String(string BASE64_functionstring)

Loads a function from a BASE64-string.

To convert a function into a BASE64-string, use ConvertFunction_ToBase64String

Returns nil in case of an error


Returnvalues:
function func
the loaded function

Parameters:
string BASE64_functionstring
the function, stored as BASE64-string


^ Reaper version 5.975 Ultraschall version 4.00ConvertFunction_FromHexString

Lua: function function = ultraschall.ConvertFunction_FromHexString(string HEX_functionstring)

Loads a function from a HEX-string.

To convert a function into a HEX-string, use ConvertFunction_ToHexString

Returns nil in case of an error


Returnvalues:
function func
the loaded function

Parameters:
string HEX_functionstring
the function, stored as HEX-string


^ Reaper version 5.975 Ultraschall version 4.00ConvertFunction_ToBase64String

Lua: string BASE64_functionstring = ultraschall.ConvertFunction_ToBase64String(function to_convert_function, boolean debug)

Converts a function into a BASE64-string.

To load a function from a BASE64-string, use ConvertFunction_FromBase64String

Returns nil in case of an error


Returnvalues:
string BASE64_functionstring
the function, stored as BASE64-string

Parameters:
function to_convert_function
the function, that you want to convert
boolean debug
true, store debug-information as well; false, only store function


^ Reaper version 5.975 Ultraschall version 4.00ConvertFunction_ToHexString

Lua: string HEX_functionstring = ultraschall.ConvertFunction_ToHexString(function to_convert_function, boolean debug)

Converts a function into a HEX-string.

To load a function from a HEX-string, use ConvertFunction_FromHexString

Returns nil in case of an error


Returnvalues:
string HEX_functionstring
the function, stored as HEX-string

Parameters:
function to_convert_function
the function, that you want to convert
boolean debug
true, store debug-information as well; false, only store function


^ Reaper version 5.92 Ultraschall version 4.00MakeFunctionUndoable

Lua: boolean retval, string current_UndoMessage, retvals_1, ..., retvals_2 = ultraschall.MakeFunctionUndoable(function Func, string UndoMessage, integer Flag, Func_parameters_1, ... Func_parameters_n)

Run the function Func and create an undopoint for this function. You can also give an UndoMessage and a flag for Reaper to use.
All parameters needed by Func follow after parameter Flag, as if it would be the normal parameters.
This should make creating undo-points much much easier...

Note: Reaper will use the undo-point only for functions, who do "undo"-able things. If you don't have something of that kind(no creating a track or something), Reaper will not create an undo-point.

Returns false in case of an error

Returnvalues:
boolean retval
true, undoing was successful; false, undoing wasn't successful
string current_UndoMessage
the current UndoMessage for the last action done by Reaper. Use this so see, if getting an undo-point was successful
retvals_1 ... retvals_2
the returnvalues, as returned by function Func

Parameters:
function Func
the function, that you want to create an undo-point for
string UndoMessage
the undo-message to be displayed by Reaper in the Undo-history
integer Flag
you can set a flag, if you want, for this undo-point
Func_parameters_1, ... Func_parameters_n
the parameters, as needed by the function Func; will be given to Func as provided by you


^ Reaper version 5.965 Ultraschall version 4.00RunLuaSourceCode

Lua: boolean retval = ultraschall.RunLuaSourceCode(string code)

runs the Lua-code stored in the parameter code

Does not check for validity and syntaxerrors in the code!

You can also add new callable functions that way. Just put function-declarations in the parameter code.

For instance from the following code:

code=function main() reaper.MB("I'm only run, when my parent function main is called", "", 0) end

   reaper.MB("I'm run immediately", "", 0)"

when called by

ultraschall.RunLuaSourceCode(code)

only the line reaper.MB("I'm run immediately", "", 0) will be run immediately. If you want to run the function main as well, you need to explicitly call it with main()

returns false in case of an error; nil, in case of an syntax/lua-error in the code itself


Returnvalues:
boolean retval
true, code was run successfully; false, code wasn't successfully; nil, code had an error in it, probably syntax error

Parameters:
string code
the code, that you want to execute; you can also add new functions that way


^ Reaper version 5.975 Ultraschall version 4.00StoreFunctionInExtState

Lua: boolean retval = ultraschall.StoreFunctionInExtState(string section, string key, function func, boolean debug)

Stores a function into an extstate. You can store it's debug-information as well.

To load the function again, use LoadFunctionFromExtState

Returns false in case of an error


Returnvalues:
boolean retval
true, setting was successful; false, it was unsuccessful

Parameters:
string section
the sectionname of the extstate
string key
the keyname of the extstate
function func
the function, that you want to store
boolean debug
true, store debug-values as well; false, don't store the debug-values as well


^ Reaper version 6.10 Ultraschall version 4.2GMem_GetValues_VideoSamplePeeker

Lua: number play_pos, integer samplerate, integer num_channels, integer requested_samplebuffer_length, table samplebuffer = ultraschall.GMem_GetValues_VideoSamplePeeker(optional integer samplesize)

For usage together with the JSFX-fx- "Video Sample Peeker", which sends samples to a gmem, that can be used(for instance by video processor's presets "Synthesis: Decorative Oscilloscope with Blitter" and "Synthesis: Decorative Spectrum Analyzer").

Ths returns all important values and the samples-values.

You need to use the samples according to samplerate and number of channels to be able to do something with it.

The overall maximum sample-buffer provided by the JSFX is 2 seconds.

Returns nil in case of an error


Returnvalues:
number play_pos
the playposition, when the sample has been re
integer samplerate
the samplerate of the sampledata
integer num_channels
the number of channels within the sampledata
integer requested_samplebuffer_length
the length of the requested buffer; maximum is the number of values for about 2 seconds
table samplebuffer
the values themselves

Parameters:
optional integer samplesize
the samplesize you want to get; nil, return the whole 2-seconds-samplebuffer(takes a lot of resources)


^ Reaper version 6.10 Ultraschall version 4.2GMem_Read_ValueRange

Lua: table gmem_values = ultraschall.GMem_Read_ValueRange(integer startindex, integer number_of_indices, optional boolean use_gmem_indices_for_table, optional string gmem_attachname)

Returns a table with all values of a gmem between startindex and startindex+numberofindices. You can optionally set a specific gmem-attachname or leave it blank to get the values from the currently attached gmem.

Set usegmemindicesfortable=true, so have the index of the table reflect the index of the gmems.

Note: Keep in mind, that requesting tons of gmem-values will use up a lot of resources, so to to just get, what you need to avoid hanging gui.

Returns nil in case of an error


Returnvalues:
table gmem_values
the requested values.

Parameters:
integer startindex
the first index you want to request; must be 0 or higher
integer number_of_indices
the number of values to request, from startindex onwards
optional boolean use_gmem_indices_for_table
true, index the table according to gmem-index; false or nil, just index from 1 onwards
optional string gmem_attachname
the attached gmem, from which you want to get the values; nil, use the currently attached gmem


^ Reaper version 6.02 Ultraschall version 4.1Gmem_GetCurrentAttachedName

Lua: string current_gmem_attachname = ultraschall.Gmem_GetCurrentAttachedName()

returns nil if no gmem had been attached since addition of Ultraschall-API to the current script

Returnvalues:
string current_gmem_attachname
the name of the currently attached gmem


^ Reaper version 5.975 SWS version 2.9.7 Ultraschall version 4.1SetLiceCapExe

Lua: boolean retval = ultraschall.SetLiceCapExe(string PathToLiceCapExecutable)

Sets the path and filename of the LiceCap-executable

Note: Doesn't work on Linux, as there isn't a Linux-port of LiceCap yet.

Returns false in case of error.

Returnvalues:
boolean retval
false in case of error; true in case of success

Parameters:
string SetLiceCapExe
the LiceCap-executable with path


^ Reaper version 5.975 SWS version 2.9.7 Ultraschall version 4.1SetupLiceCap

Lua: boolean retval = ultraschall.SetupLiceCap(string output_filename, string title, integer titlems, integer x, integer y, integer right, integer bottom, integer fps, integer gifloopcount, integer stopafter, integer prefs)

Sets up an installed LiceCap-instance.

To choose the right LiceCap-version, run the action 41298 - Run LICEcap (animated screen capture utility)

Note: Doesn't work on Linux, as there isn't a Linux-port of LiceCap yet.

Returns false in case of error.

Returnvalues:
boolean retval
false in case of error; true in case of success

Parameters:
string output_filename
the output-file; you can choose whether it shall be a gif or an lcf by giving it the accompanying extension "mylice.gif" or "milice.lcf"; nil, keep the current outputfile
string title
the title, which shall be shown at the beginning of the licecap; newlines will be exchanged by spaces, as LiceCap doesn't really support newlines; nil, keep the current title
integer titlems
how long shall the title be shown, in milliseconds; nil, keep the current setting
integer x
the x-position of the LiceCap-window in pixels; nil, keep the current setting
integer y
the y-position of the LiceCap-window in pixels; nil, keep the current setting
integer right
the right side-position of the LiceCap-window in pixels; nil, keep the current setting
integer bottom
the bottom-position of the LiceCap-window in pixels; nil, keep the current setting
integer fps
the maximum frames per seconds, the LiceCap shall have; nil, keep the current setting
integer gifloopcount
how often shall the gif be looped?; 0, infinite looping; nil, keep the current setting
integer stopafter
stop recording after xxx milliseconds; nil, keep the current setting
integer prefs
the preferences-settings of LiceCap, which is a bitfield; nil, keep the current settings
&1 - display in animation: title frame - checkbox
&2 - Big font - checkbox
&4 - display in animation: mouse button press - checkbox
&8 - display in animation: elapsed time - checkbox
&16 - Ctrl+Alt+P pauses recording - checkbox
&32 - Use .GIF transparency for smaller files - checkbox
&64 - Automatically stop after xx seconds - checkbox          


^ Reaper version 5.975 Ultraschall version 4.00LoadFunctionFromExtState

Lua: function function = ultraschall.LoadFunctionFromExtState(string section, string key)

Loads a function from an extstate, if it has been stored in there before. The extstate must contain a valid function. If something else is stored, the loaded "function" might crash Lua!

To store the function, use StoreFunctionInExtState

Returns false in case of an error


Returnvalues:
function func
the stored function, that you want to (re-)load

Parameters:
string section
the sectionname of the extstate
string key
the keyname of the extstate


^ Reaper version 5.965 Ultraschall version 4.00PrintProgressBar

Lua: boolean retval, string ProgressString, integer percentage, integer progress_position = ultraschall.PrintProgressBar(boolean show, integer length, integer maximumvalue, integer currentvalue, boolean percentage, integer offset, optional string toptext, optional string bottomtext)

Calculate a simple progressbar, which can be optionally displayed in the ReaScript console; Will clear the console before displaying the next updated progressbar.

Will update it only, if the current-value of last time this function got called is different from the current one or toptext or bottomtext changed.

You can also use the returnvalues to draw your own progressbar, e.g. in a gfx.init-window

If you need to calculate a new progressbar, after the former got to 100%, it is wise to call ResetProgressBar, or it might not update the first time you call this function.

Returns false in case of an error


Returnvalues:
boolean retval
true, displaying was successful; false, displaying wasn't successful
string ProgressString
the progressbar including its full statuses and layout
integer percentage
the progression of the progressbar in percent
integer progress_position
the current progress-position, relative to length and maximumvalue

Parameters:
boolean show
true, show progressbar in the ReaScript-console; false, don't show it there
integer length
the length of the progressbar in characters. Minimum is 10.
integer maximumvalue
the maximum integer-value, to which to count; minimum 1
integer currentvalue
the current integer-value, at which we are with counting, minimum 0
boolean percentage
true, show percentage in progressbar; false, show only progressbar
integer offset
an offset to be added before the progressbar, so you can indent it
optional string toptext
an optional string, that shall be displayed above the progressbar
optional string bottomtext
an optional string, that shall be displayed below the progressbar


^ Reaper version 5.965 Ultraschall version 4.00ResetProgressBar

Lua: ultraschall.ResetProgressBar()

Resets the initial-values of the progressbar. Should be called, if you want to start a new progressbar after you filled up the former one, or you may have update-issues.



^ Reaper version 6.02 Ultraschall version 4.1BringReaScriptConsoleToFront

Lua: ultraschall.BringReaScriptConsoleToFront()

Brings Reaper's ReaScriptConsole-window to the front, when it's opened.


^ Reaper version 5.965 JS version 0.962 Ultraschall version 4.00CloseReaScriptConsole

Lua: boolean retval = ultraschall.CloseReaScriptConsole()

Closes the ReaConsole-window, if opened.

Returns false in case of an error

Returnvalues:
boolean retval
true, if there is a mute-point; false, if there isn't one


^ Reaper version 5.95 Ultraschall version 4.00GetReaperColorThemesPath

Lua: string reaper_colorthemes_path = ultraschall.GetReaperColorThemesPath()

Returns path to Reaper's color-theme-folder

Returnvalues:
string reaper_colorthemes_path
the path of the color-theme-folder of Reaper


^ Reaper version 5.95 Ultraschall version 4.00GetReaperJSFXPath

Lua: string reaper_jsfx_path = ultraschall.GetReaperJSFXPath()

Returns path to Reaper's JSFX-plugin-folder

Returnvalues:
string reaper_jsfx_path
the path of the JSFX-plugin-folder of Reaper


^ Reaper version 5.95 Ultraschall version 4.00GetReaperScriptPath

Lua: string reaper_script_path = ultraschall.GetReaperScriptPath()

Returns path to Reaper's script-folder

Returnvalues:
string reaper_script_path
the path of the scripts-folder of Reaper


^ Reaper version 5.95 Ultraschall version 4.00GetReaperWebRCPath

Lua: string reaper_webrc_path, string user_webrc_path = ultraschall.GetReaperWebRCPath()

Returns path to the Web-RC-folder for Reaper as well as for the user-webrc-pages.

Returnvalues:
string reaper_script_path
the path of the JSFX-plugin-folder of Reaper


^ Reaper version 6.02 Ultraschall version 4.2CharacterCodes_ReverseLookup

Lua: string Character, optional boolean special_modifier, optional boolean shift, optional boolean control, optional boolean alt, optional boolean win, optional boolean opt, optional boolean cmd = ultraschall.CharacterCodes_ReverseLookup(integer byte1, integer byte2, integer byte3, optional integer lang)

returns the character-code+modifiers of a control-message-character as sent by reaper.StuffMIDIMessage with mode=1 they will be returned as shown in the add shortcut-dialog, though the keyboard-modifiers are returned as extra returnvalues.

optionally, you can select a multitude of keymaps for localization

Note: as there are many different language-keymaps out there, I tried to use some common ones. That also means, that they might be different in detail to your used one. So the only keymap 100% reliable is the default-us-english one.

returns nil in case of an error


Returnvalues:
string Character
the character/midi-message associated with this character-code
optional boolean special_modifier
true, this is the special modifier(byte1=255); false, regular character/midimessage
the special modifier stores multizoom, multirotate, multiswipe, mousewheel, mediakbd-buttons
optional boolean shift
true, shift-key is needed; false, shift-key is not needed
optional boolean control
true, ctrl-key is needed; false, ctrl-key is not needed
optional boolean alt
true, alt-key is needed; false, alt-key is not needed
optional boolean win
true, win-key is needed; false, win-key is not needed
optional boolean opt
true, opt-key is needed; false, opt-key is not needed - (mac only)
optional boolean cmd
true, cmd-key is needed; false, cmd-key is not needed - (mac only)

Parameters:
integer byte1
the first byte of the StuffMIDIMessage, usually stores modifiers
integer byte2
the first byte of the StuffMIDIMessage, usually stores character-codes
integer byte3
the first byte of the StuffMIDIMessage, usually stores additional information
optional integer lang
the languagekeymap used. The following list includes the specific keymap supported
so they might differ in details. I used the ones supported by Windows 7
nil and 1, englisch(usa) default
2, german
3, arabian(saudi arabia)
4, catalan(spain)
5, greek(greece)
6, french(france)
7, hebrew(israel)
8, icelandic(iceland)
9, italian(italy)
10, japanese(japan)
11, russian(russian federation)
12, turkish(turkey)
13, indonesian(indonesia)
14, hindi(india)
15, punjabi(india)
16, chinese_simplified(china)
17, portuguese(portugal)
18, spanish(spain)


^ Reaper version 6.02 Ultraschall version 4.2CharacterCodes_ReverseLookup_KBIni

Lua: string Character, optional boolean special_modifier, optional boolean shift, optional boolean control, optional boolean alt, optional boolean win, optional boolean opt, optional boolean cmd = ultraschall.CharacterCodes_ReverseLookup_KBIni(integer byte1, integer byte2, optional integer lang)

returns the character-code+modifiers of a control-message-character as stored in the KEY-entries in the reaper-kb.ini they will be returned as shown in the add shortcut-dialog, though the keyboard-modifiers are returned as extra returnvalues.

optionally, you can select a multitude of keymaps for localization

Note: as there are many different language-keymaps out there, I tried to use some common ones. That also means, that they might be different in detail to your used one. So the only keymap 100% reliable is the default-us-english one.

returns nil in case of an error


Returnvalues:
string Character
the character/midi-message associated with this KEY-entry-character-code
optional boolean special_modifier
true, this is the special modifier(byte1=255); false, regular character/midimessage
the special modifier stores multizoom, multirotate, multiswipe, mousewheel, mediakbd-buttons
optional boolean shift
true, shift-key is needed; false, shift-key is not needed
optional boolean control
true, ctrl-key is needed; false, ctrl-key is not needed
optional boolean alt
true, alt-key is needed; false, alt-key is not needed
optional boolean win
true, win-key is needed; false, win-key is not needed
optional boolean opt
true, opt-key is needed; false, opt-key is not needed - (mac only)
optional boolean cmd
true, cmd-key is needed; false, cmd-key is not needed - (mac only)

Parameters:
integer byte1
the first byte of the kb.ini-KEY-entry, usually stores modifiers
integer byte2
the first byte of the kb.ini-KEY-entry, usually stores character-codes
optional integer lang
the languagekeymap used. The following list includes the specific keymap supported
so they might differ in details. I used the ones supported by Windows 7
nil and 1, englisch(usa) default
2, german
3, arabian(saudi arabia)
4, catalan(spain)
5, greek(greece)
6, french(france)
7, hebrew(israel)
8, icelandic(iceland)
9, italian(italy)
10, japanese(japan)
11, russian(russian federation)
12, turkish(turkey)
13, indonesian(indonesia)
14, hindi(india)
15, punjabi(india)
16, chinese_simplified(china)
17, portuguese(portugal)
18, spanish(spain)


^ Reaper version 6.02 Ultraschall version 4.2KBIniGetAllShortcuts

Lua: integer number_of_shortcuts, table shortcut_attributes = ultraschall.KBIniGetAllShortcuts(optional boolean exclude_factory_default, optional integer lang)

returns all shortcuts currently set in the current Reaper-installation(as stored in reaper-kb.ini) as a handy table.

The table is of the following format: KeyTable[shortcut_idx]["Code1"] - the first value in a KEY-entry KeyTable[shortcut_idx]["Code2"] - the second value in a KEY-code KeyTable[shortcut_idx]["ActionCommandID"] - the action-command id or command-id-number KeyTable[shortcut_idx]["Section"] - the section: 0 - Main, 100 - Main (alt recording), 32060 - MIDI Editor, 32061 - MIDI Event List Editor, 32062 - MIDI Inline Editor, 32063 - Media Explorer KeyTable[shortcut_idx]["ShortcutName"] - the keyname as shown in the Add shortcut-dialog; localization depending on language-parameter KeyTable[shortcut_idx]["Modifier_SpecialModifier"] - true, the special modifier(for mediakbd, mousewheel, multitouch/zoom/swipe); false, midi or regular key KeyTable[shortcut_idx]["Modifier_Shift"] - true, shift is needed; false, shift is not needed as modifier KeyTable[shortcut_idx]["Modifier_Control"] - true, control is needed; false, control is not needed as modifier KeyTable[shortcut_idx]["Modifier_Alt"] - true, alt is needed; false, alt is not needed as modifier KeyTable[shortcut_idx]["Modifier_Win"] - true, win is needed; false, win is not needed as modifier(for windows) KeyTable[shortcut_idx]["Modifier_Opt"] - true, opt is needed; false, opt is not needed as modifier(for mac) KeyTable[shortcut_idx]["Modifier_Cmd"] - true, cmd is needed; false, cmd is not needed as modifier(for mac) KeyTable[shortcut_idx]["Global_Scope"] - is this shortcut global; -1, no; 1, global; 101, global+textfields KeyTable[shortcut_idx]["Global_Section"] - the section in which this shortcut is global; 102(main), 103(main alt.)

returns -1 in case of an error


Returnvalues:
integer number_of_shortcuts
the number of found shortcuts
table shortcut_attributes
a nice and handy table of all shortcut-attributes

Parameters:
optional boolean exclude_factory_default
true, will only return the custom shortcuts; false or nil, returns all shortcuts, including factory default ones(usually not stored in kb.ini)
optional integer lang
the languagekeymap used. The following list includes the specific keymap supported
so they might differ in details. I used the ones supported by Windows 7
nil and 1, englisch(usa) default
2, german
3, arabian(saudi arabia)
4, catalan(spain)
5, greek(greece)
6, french(france)
7, hebrew(israel)
8, icelandic(iceland)
9, italian(italy)
10, japanese(japan)
11, russian(russian federation)
12, turkish(turkey)
13, indonesian(indonesia)
14, hindi(india)
15, punjabi(india)
16, chinese_simplified(china)
17, portuguese(portugal)
18, spanish(spain)


^ Reaper version 5.965 Ultraschall version 4.00print

Lua: print(parameter_1 to parameter_n)

replaces Lua's own print-function, that is quite useless in Reaper.

displays \0-characters as .

Converts all parametes given into string using tostring() and displays them in the ReaScript-console, separated by a newline and ending with a newline.


Parameters:
parameter_1 to parameter_n
the parameters, that you want to have printed out


^ Reaper version 5.965 Ultraschall version 4.00print2

Lua: print2(parameter_1 to parameter_n)

replaces Lua's own print-function.

shows \0-characters as .

Converts all parametes given into string using tostring() and displays them as a MessageBox, separated by two spaces.

Parameters:
parameter_1 to parameter_n
the parameters, that you want to have printed out


^ Reaper version 5.965 SWS version 2.9.7 Ultraschall version 4.00print3

Lua: print(parameter_1 to parameter_n)

like print, but puts the parameters into the clipboard.

Converts all parametes given into string using tostring() and puts them into the clipboard, with each parameter separated by two spaces.
Unlike print and print2, this does NOT end with a newline!

Note: \0-characters will be seen as string-termination, so strings may be truncated. Please replace \0 with string.gsub, if you need to have the full string with all nil-values included.


Parameters:
parameter_1 to parameter_n
the parameters, that you want to have put into the clipboard


^ Reaper version 5.965 Ultraschall version 4.00print_alt

Lua: print_alt(parameter_1 to parameter_n)

replaces Lua's own print-function, that is quite useless in Reaper.

shows \0-characters as .

like print, but separates the entries by a two spaced, not a newline


Parameters:
parameter_1 to parameter_n
the parameters, that you want to have printed out


^ Reaper version 5.965 Ultraschall version 4.00print_update

Lua: print_update(parameter_1 to parameter_n)

replaces Lua's own print-function, that is quite useless in Reaper.

Converts all parametes given into string using tostring() and displays them in the ReaScript-console, separated by two spaces, ending with a newline.

Shows \0-characters as .

This is like print, but clears console everytime before displaying the values. Good for status-display, that shall not scroll.


Parameters:
parameter_1 to parameter_n
the parameters, that you want to have printed out


^ Reaper version 5.40 Ultraschall version 4.00IsItemInTrack

Lua: boolean retval = ultraschall.IsItemInTrack(integer tracknumber, integer itemIDX)

checks, whether a given item is part of the track tracknumber

returns true, if the itemIDX is part of track tracknumber, false if not, nil if no such itemIDX or Tracknumber available

Returnvalues:
boolean retval
true, if item is in track, false if item isn't in track

Parameters:
integer itemIDX
the number of the item to check of
integer tracknumber
the number of the track to check in, with 1 for track 1, 2 for track 2, etc.


^ Reaper version 5.40 Ultraschall version 4.00IsItemInTrack2

Lua: boolean retval, integer tracknumber = ultraschall.IsItemInTrack2(MediaItem MediaItem, integer tracknumber)

Checks, whether a MediaItem is in track with tracknumber.

see IsItemInTrack to use itemidx instead of the MediaItem-object. see IsItemInTrack3 to check against multiple tracks at once using a trackstring.

returns nil in case of error


Returnvalues:
boolean retval
true, if item is in track; false, if not
integer tracknumber
the tracknumber of the track, in which the item lies

Parameters:
MediaItem MediaItem
the MediaItem, of which you want to know the track is is placed in
integer tracknumber
the tracknumber to check the parent track of the MediaItem against, with 1 for track 1, etc


^ Reaper version 5.40 Ultraschall version 4.00IsItemInTrack3

Lua: boolean retval = ultraschall.IsItemInTrack3(MediaItem MediaItem, string trackstring)

Checks, whether a MediaItem is in any of the tracks, given by trackstring.

see IsItemInTrack to use itemidx instead of the MediaItem-object. see IsItemInTrack2 to check against only one track.

returns nil in case of error


Returnvalues:
boolean retval
true, if item is in track; false, if not
string trackstring
a string with all tracknumbers, separated by commas; 1 for track 1, 2 for track 2, etc

Parameters:
MediaItem MediaItem
the MediaItem, of which you want to know the track is is placed in
string trackstring
a string with all tracknumbers, separated by commas; 1 for track 1, 2 for track 2, etc


^ Reaper version 6.19 Ultraschall version 4.2IsOS_Mac

Lua: boolean is_mac, integer number_of_bits = ultraschall.IsOS_Mac()

returns, if the current operating system is mac-osx

Returnvalues:
boolean is_mac
true, if the operating-system is mac-osx; false if not
integer bits
the number of bits of the operating-system. Either 32 or 64 bit.; nil if is_mac=false


^ Reaper version 5.40 Ultraschall version 4.00IsOS_Other

Lua: boolean is_other, integer number_of_bits = ultraschall.IsOS_Other()

returns, if the current operating system is neither mac or win

Returnvalues:
boolean is_other
true, if the operating-system is neither mac or win; false if not
integer bits
the number of bits of the operating-system. Either 32 or 64 bit.; nil if is_other=false


^ Reaper version 5.40 Ultraschall version 4.00IsOS_Windows

Lua: boolean is_windows, integer number_of_bits = ultraschall.IsOS_Windows()

returns, if the current operating system is windows

Returnvalues:
boolean is_windows
true, if the operating-system is windows; false if not
integer bits
the number of bits of the operating-system. Either 32 or 64 bit; nil if is_win==false


^ Reaper version 5.40 Ultraschall version 4.00IsObjectValidReaperObject

Lua: boolean retval, string objecttype = ultraschall.IsObjectValidReaperObject(Reaperobject object)

checks, if object is a valid Reaper-object. It also returns the type of that Reaper-object.

Returnvalues:
boolean retval
true, if it's a valid Reaper-object; false, if not
string objecttype
the type of the parameter of object
the following types can be returned:
ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source, None

Parameters:
Reaperobject object
a Reaper-object of the following types:
ReaProject, MediaTrack, MediaItem, MediaItem_Take, TrackEnvelope, PCM_source
returns None if the object isn't a valid Reaper-object


^ Reaper version 5.40 Ultraschall version 4.00IsValidGuid

Lua: boolean retval = ultraschall.IsValidGuid(string guid, boolean strict)

Checks, if guid is a valid guid. Can also be used for strings, that contain a guid somewhere in them(strict=false)

A valid guid is a string that follows the following pattern:
{........-....-....-....-............}
where . is a hexadecimal value(0-F)

Returns false in case of error

Returnvalues:
boolean retval
true, guid is/contains a valid guid; false, guid isn't/does not contain a valid guid

Parameters:
string guid
the guid to check for validity
boolean strict
true, guid must only be the valid guid; false, guid must contain a valid guid somewhere in it(means, can contain trailing or preceding characters)


^ Reaper version 5.965 Ultraschall version 4.00IsWithinTimeRange

Lua: boolean retval = ultraschall.IsWithinTimeRange(number point_in_time, number start, number stop)

returns if time is between(including) start and stop.

returns false in case of an error

Returnvalues:
boolean retval
true, time is between start and stop; false, it isn't

Parameters:
number point_in_time
the time in seconds, to check for
number start
the starttime in seconds, within to check for
number stop
the endtime in seconds, within to check for


^ Reaper version 6.10 Ultraschall version 4.1Create2DTable

Lua: table 2dtable = ultraschall.Create2DTable(integer maxx, integer maxy, optional anytype defval)

creates a 2-dimensional table with x-lines and y-rows, of which all entries are indexable right away.

It also has two additional fields ["x"] and ["y"] who hold the x and y-dimensions of the table you've set for later reference.

returns nil in case of an error


Returnvalues:
table 2dtable
the 2d-table you've created

Parameters:
integer maxx
the number of rows in the table(x-dimension)
integer maxy
the number of lines in the table(y-dimension)
optional anytype defval
the default-value to set in each field, can be any type


^ Reaper version 6.10 Ultraschall version 4.1Create3DTable

Lua: table 3dtable = ultraschall.Create3DTable(integer maxx, integer maxy, integer maxz, optional anytype defval)

creates a 3-dimensional table with x-lines and y-rows and z-depths, of which all entries are indexable right away.

It also has two additional fields ["x"], ["y"] and ["z"] who hold the x, y and z-dimensions of the table you've set for later reference.

returns nil in case of an error


Returnvalues:
table 3dtable
the 3d-table you've created

Parameters:
integer maxx
the number of rows in the table(x-dimension)
integer maxy
the number of lines in the table(y-dimension)
integer maxz
the number of depths in the table(z-dimension)
optional anytype defval
the default-value to set in each field, can be any type


^ Reaper version 6.10 Ultraschall version 4.1CreateMultiDimTable

Lua: table multidimtable = ultraschall.CreateMultiDimTable(optional anytype defval, optional integer dimension1, optional integer dimension2, ... , optional integer dimensionN)

creates a multidimensional table

It also adds additional fields ["dimension1"] to ["dimension10"] who hold the number of available entries in this dimension for later reference.

It supports up to 10 dimensions. Note: the more dimensions, the more memory you need and the longer it takes to create the table.

returns nil in case of an error


Returnvalues:
table multidimtable
the multidimensional-table you've created

Parameters:
optional anytype defval
the default-value to set in each field, can be any type; set to nil to keep empty
integer dimension1
the number of entries in the first dimension of the table
integer dimension2
the number of entries in the second dimension of the table
integer dimensionN
the number of entries in the n'th dimension of the table


^ Reaper version 5.40 Ultraschall version 4.1GetApiVersion

Lua: number versionnumber, string majorversion, string date, string subversion, string tagline, string buildnumber = ultraschall.GetApiVersion()

returns the version, release-date and if it's a beta-version plus the currently installed hotfix

Returnvalues:
number versionnumber
a number, that you can use for comparisons like, "if requestedversion>versionnumber then"
string majorversion
the current Api-major-version
string date
the release date of this api-version
string subversion
a subversion-number of a major-version
string tagline
the tagline of the current release
string hotfix_date
the release-date of the currently installed hotfix ($ResourceFolder/ultraschall_api/ultraschall_hotfixes.lua); XX_XXX_XXXX if no hotfix is installed currently
string buildnumber
the build-number of the current release


^ Reaper version 6.17 Ultraschall version 4.2GetOS

Lua: string operating_system, integer bits = ultraschall.GetOS()

Returns operating system and if it's a 64bit/32bit-operating system.

Returnvalues:
string operating_system
the operating system used; usually "Win", "Mac" or "Other"(e.g. when Linux is used)
integer bits
the number of bits of the operating-system. Either 32 or 64 bit.


^ Reaper version 5.975 Ultraschall version 4.00GetReaperAppVersion

Lua: integer majorversion, integer subversion, string bits, string operating_system, boolean portable, optional string betaversion = ultraschall.GetReaperAppVersion()

Returns operating system and if it's a 64bit/32bit-operating system.

Returnvalues:
integer majorversion
the majorversion of Reaper. Can be used for comparisions like "if version<5 then ... end".
integer subversion
the subversion of Reaper. Can be used for comparisions like "if subversion<96 then ... end".
string bits
the number of bits of the reaper-app
string operating_system
the operating system, either "Win", "OSX" or "Other"
boolean portable
true, if it's a portable installation; false, if it isn't a portable installation
optional string betaversion
if you use a pre-release of Reaper, this contains the beta-version, like "rc9" or "+dev0423" or "pre6"


^ Reaper version 6.19 Ultraschall version 4.2OpenURL

Lua: integer retval = ultraschall.OpenURL(string url)

Opens the URI with the standard-browser installed in your system.

returns -1 in case of an error

Parameters:
string url
the url to be opened in the browser; will check for :// in it for validity!


^ Reaper version 5.40 Ultraschall version 4.00PreventCreatingUndoPoint

Lua: ultraschall.PreventCreatingUndoPoint()

Prevents creation of an Undo-point. Only useful in non-defer-scripts.


^ Reaper version 5.40 SWS version 2.9.7 Ultraschall version 4.00ReturnsMinusOneInCaseOfError_Arzala

Lua: integer retval = ultraschall.ReturnsMinusOneInCaseOfError_Arzala()

Returns -1 in case of an error

Returnvalues:
integer retval
returns -1 in case of error


^ Reaper version 5.95 Ultraschall version 4.00RunBackgroundHelperFeatures

Lua: ultraschall.RunBackgroundHelperFeatures(boolean switch_on)

Starts background-scripts supplied with the Ultraschall-API, like:


Parameters:
boolean switch_on
true, start the background-scripts/start unstarted background-helper-scripts; false, stop all background-helper-scripts


^ Reaper version 6.10 Ultraschall version 4.1TimeToMeasures

Lua: number measure = ultraschall.TimeToMeasures(ReaProject project, number Time)

a function which converts a time into current projects time-measures only useful, when there are no tempo-changes in the project

returns nil in case of an error


Returnvalues:
number measure
the measures, that parameter time needs to be reflected

Parameters:
ReaProject project
ReaProject to use the timesignature-settings from
number time
in seconds, the time to convert into a time-measurment, which can be
used in config-variable "prerollmeas"


^ Reaper version 5.975 Ultraschall version 4.00get_action_context_MediaItemDiff

Lua: MediaItem MediaItem, MediaItem_Take MediaItem_Take, MediaItem MediaItem_unlocked, boolean Item_moved, number StartDiffTime, number EndDiffTime, number LengthDiffTime, number OffsetDiffTime = ultraschall.get_action_context_MediaItemDiff(optional boolean exlude_mousecursorsize, optional integer x, optional integer y)

Returns the currently clicked MediaItem, Take as well as the difference of position, end, length and startoffset since last time calling this function.
Good for implementing ripple-drag/editing-functions, whose position depends on changes in the currently clicked MediaItem.
Repeatedly call this (e.g. in a defer-cycle) to get all changes made, during dragging position, length or offset of the MediaItem underneath mousecursor.

This function takes into account the size of the start/end-drag-mousecursor, that means: if mouse-position is within 3 pixels before start/after end of the item, it will get the correct MediaItem.
This is a workaround, as the mouse-cursor changes to dragging and can still affect the MediaItem, even though the mouse at this position isn't above a MediaItem anymore.
To be more strict, set exlude_mousecursorsize to true. That means, it will only detect MediaItems directly beneath the mousecursor. If the mouse isn't above a MediaItem, this function will ignore it, even if the mouse could still affect the MediaItem.
If you don't understand, what that means: simply omit exlude_mousecursorsize, which should work in almost all use-cases. If it doesn't work as you want, try setting it to true and see, whether it works now.    

Returnvalues:
MediaItem MediaItem
the MediaItem at the current mouse-position; nil if not found
MediaItem_Take MediaItem_Take
the MediaItem_Take underneath the mouse-cursor
MediaItem MediaItem_unlocked
if the MediaItem isn't locked, you'll get a MediaItem here. If it is locked, this retval is nil
boolean Item_moved
true, the item was moved; false, only a part(either start or end or offset) of the item was moved
number StartDiffTime
if the start of the item changed, this is the difference;
  positive, the start of the item has been changed towards the end of the project
  negative, the start of the item has been changed towards the start of the project
  0, no changes to the itemstart-position at all
number EndDiffTime
if the end of the item changed, this is the difference;
  positive, the end of the item has been changed towards the end of the project
  negative, the end of the item has been changed towards the start of the project
  0, no changes to the itemend-position at all
number LengthDiffTime
if the length of the item changed, this is the difference;
  positive, the length is longer
  negative, the length is shorter
  0, no changes to the length of the item
number OffsetDiffTime
if the offset of the item-take has changed, this is the difference;
  positive, the offset has been changed towards the start of the project
  negative, the offset has been changed towards the end of the project
  0, no changes to the offset of the item-take
Note: this is the offset of the take underneath the mousecursor, which might not be the same size, as the MediaItem itself!
So changes to the offset maybe changes within the MediaItem or the start of the MediaItem!
This could be important, if you want to affect other items with rippling.

Parameters:
optional boolean exlude_mousecursorsize
false or nil, get the item underneath, when it can be affected by the mouse-cursor(dragging etc): when in doubt, use this
true, get the item underneath the mousecursor only, when mouse is strictly above the item,
      which means: this ignores the item when mouse is not above it, even if the mouse could affect the item
optional integer x
nil, use the current x-mouseposition; otherwise the x-position in pixels
optional integer y
nil, use the current y-mouseposition; otherwise the y-position in pixels


^ Reaper version 5.40 Ultraschall version 4.00API_TempPath

Lua: ultraschall.API_TempPath

Contains the path to the temp-folder of the Ultraschall-API.


^ Reaper version 5.40 Ultraschall version 4.00Api_InstallPath

Lua: ultraschall.Api_InstallPath

Contains the current path to the installation folder of the Ultraschall-Api(usually Resourcesfolder/UserPlugins)


^ Reaper version 5.40 Ultraschall version 4.00Api_Path

Lua: ultraschall.Api_Path

Contains the current path of the Ultraschall-Api-folder ResourcePath/UserPlugins/ultraschall_api/


^ Reaper version 5.40 Ultraschall version 4.00Euro

Lua: ultraschall.Euro

Holds the Euro-currency-symbol, which is hard to type in Reaper's own IDE.


^ Reaper version 5.40 Ultraschall version 4.00Separator

Lua: ultraschall.Separator

Contains the correct separator for your system. / on Mac, \ on Windows. Use them, if you want to create windows and mac-compliant scripts that have file operations.


^ Reaper version 5.40 Ultraschall version 4.00StartTime

Lua: ultraschall.StartTime

Contains the correct starting time of the current instance of the Ultraschall-Framework, which probably means your script, that embeds the framework.


^ Reaper version 5.965 SWS version 2.9.7 Ultraschall version 4.00GetHWInputs_Aliasnames

Lua: integer number_of_aliases, table aliases = ultraschall.GetHWInputs_Aliasnames()

Returns the aliasnames and their associated channels of the currently selected audio-device.

The returned table is of the format table[index][1] - the name of the alias table[index][2] - the hardware-input-channel, associated to this aliasname


Returnvalues:
integer number_of_aliases
the number of aliases available
table aliases
a table, that contains all alias-names and their associated Hardware-Input-channels


^ Reaper version 5.965 SWS version 2.9.7 Ultraschall version 4.00GetHWOutputs_Aliasnames

Lua: integer number_of_aliases, table aliases = ultraschall.GetHWOutputs_Aliasnames()

Returns the aliasnames and their associated channels of the currently selected audio-device.

The returned table is of the format table[index][1] - the name of the alias table[index][2] - the hardware-output-channel, associated to this aliasname


Returnvalues:
integer number_of_aliases
the number of aliases available
table aliases
a table, that contains all alias-names and their associated Hardware-Output-channels


^ Reaper version 6.05 Ultraschall version 4.2AutomationItem_Delete

Lua: boolean retval = ultraschall.AutomationItem_Delete(TrackEnvelope env, integer automationitem_idx, optional boolean preservepoints)

Deletes an Automation-Item, optionally preserves the points who are added to the underlying envelope.

returns false in case of an error

Returnvalues:
boolean retval
true, deleting was successful; false, deleting was not successful

Parameters:
TrackEnvelope env
the TrackEnvelope, in which the automation-item to be deleted is located
integer automationitem_idx
the automationitem that shall be deleted; 0, for the first one
optional boolean preservepoints
true, keep the envelopepoints and add them to the underlying envelope; nil or false, just delete the AutomationItem


^ Reaper version 6.10 Ultraschall version 4.2AutomationItem_Split

Lua: boolean retval = ultraschall.AutomationItem_Split(TrackEnvelope Env, number position, integer index, integer selected)

splits an automation-item at position in Env

returns false in case of an error

Returnvalues:
boolean retval
true, splitting was successful; false, splitting was unsuccessful

Parameters:
TrackEnvelope Env
the envelope, whose automation-item you want to split
number position
the position in seconds at wich you want to split the automation item
integer index
the index of the automation-item, that you want to split
integer selected
0, set the newly created automation item unselected
1, set it selected
2, use selection-state of the original automation-item


^ Reaper version 6.05 Ultraschall version 4.1AutomationItems_GetAll

Lua: integer number_of_automationitems, table AutomationItems_Table = ultraschall.AutomationItems_GetAll()

Returns all automation items from the current project as a handy table

The format of the table is as follows:
    AutomationItems[automationitem_idx]["Track"] - the track, in which the automation item is located
    AutomationItems[automationitem_idx]["EnvelopeObject"] - the envelope, in which the automationitem is located
    AutomationItems[automationitem_idx]["EnvelopeName"] - the name of the envelope
    AutomationItems[automationitem_idx]["AutomationItem_Index"] - the index of the automation with EnvelopeObject
    AutomationItems[automationitem_idx]["AutomationItem_PoolID"] - the pool-Id of the automation item
    AutomationItems[automationitem_idx]["AutomationItem_Position"] - the position of the automation item in seconds
    AutomationItems[automationitem_idx]["AutomationItem_Length"] - the length of the automation item in seconds
    AutomationItems[automationitem_idx]["AutomationItem_Startoffset"] - the startoffset of the automation item in seconds
    AutomationItems[automationitem_idx]["AutomationItem_Playrate"]- the playrate of the automation item
    AutomationItems[automationitem_idx]["AutomationItem_Baseline"]- the baseline of the automation item, between 0 and 1
    AutomationItems[automationitem_idx]["AutomationItem_Amplitude"]- the amplitude of the automation item, between -1 and +1
    AutomationItems[automationitem_idx]["AutomationItem_LoopSource"]- the loopsource-state of the automation item; 0, unlooped; 1, looped
    AutomationItems[automationitem_idx]["AutomationItem_UISelect"]- the selection-state of the automation item; 0, unselected; nonzero, selected
    AutomationItems[automationitem_idx]["AutomationItem_Pool_QuarteNoteLength"]- the quarternote-length

Returnvalues:
integer number_of_automationitems
the number of automation-items found in the current project
table AutomationItems_Table
all found automation-items as a handy table(see description for details)


^ Reaper version 6.10 Ultraschall version 4.2AutomationItems_GetByTime

Lua: integer found_automation_items, table automation_item_indices = ultraschall.AutomationItems_GetByTime(TrackEnvelope Env, number position)

returns all automation-items at a given position in an Envelope

returns -1 in case of an error

Returnvalues:
integer found_automation_items
the number of automation-items found; -1, in case of an error
table automation_item_indices
the indices of the found automation-items

Parameters:
TrackEnvelope Env
the envelope, whose automation-items you want to get
number position
the position in seconds from wich you want to get the automation items


^ Reaper version 5.95 Ultraschall version 4.00GetProject_AutomationItemStateChunk

Lua: string AutomationItemStateChunk = ultraschall.GetProject_AutomationItemStateChunk(string projectfilename_with_path, integer idx, optional string ProjectStateChunk)

returns the idx'th automation-item from a ProjectStateChunk.

It's the entry <POOLEDENV

returns nil in case of an error

Returnvalues:
string AutomationItemStateChunk
the statechunk of the idx'th automation-item

Parameters:
string projectfilename_with_path
the projectfile+path, from which to get the automation-item-statechunk; nil to use ProjectStateChunk
integer idx
the number of the requested automation-item from the ProjectStateChunk with 1 for the first AutomItem.
optional string ProjectStateChunk
a statechunk of a project, usually the contents of a rpp-project-file


^ Reaper version 5.95 Ultraschall version 4.00GetProject_CountAutomationItems

Lua: integer automation_items_count = ultraschall.GetProject_CountAutomationItems(string projectfilename_with_path, optional string ProjectStateChunk)

returns the number of automation-items available in a ProjectStateChunk.

It's the entry <POOLEDENV
                        
returns -1 in case of an error

Returnvalues:
integer automation_items_count
the number of automation-items

Parameters:
string projectfilename_with_path
the projectfile+path, from which to get the automation-item-count; nil to use ProjectStateChunk
optional string ProjectStateChunk
a statechunk of a project, usually the contents of a rpp-project-file; only used, when projectfilename_with_path=nil


^ Reaper version 6.02 SWS version 2.10.0.1 Ultraschall version 4.00FromClip

Lua: string clipboard_string = FromClip()

Gets a string from clipboard.

Returnvalues:
string clipboard_string
the string-content from the clipboard


^ Reaper version 5.40 Ultraschall version 4.00GetMediaItemsFromClipboard

Lua: integer count, array MediaItemStateChunkArray = ultraschall.GetMediaItemsFromClipboard()

Returns the number of mediaitems and a MediaItemStateChunkArray of the mediaitems, as stored in the clipboard.

It does it by pasting the items at the end of the project, getting them and deleting them again.

Use sparsely and with care, as it uses a lot of resources!

Returnvalues:
integer count
the number of items in the clipboard
array MediaItemStatechunkArray
the mediaitem-statechunks of the items in the clipboard. One entry for each mediaitem-statechunk.


^ Reaper version 5.52 SWS version 2.9.7 Ultraschall version 4.00GetStringFromClipboard_SWS

Lua: string clipboard_string = ultraschall.GetStringFromClipboard_SWS()

Returns the content of the clipboard as a string. Uses the SWS-function reaper.CF_GetClipboard, but does everything for you, that is needed for proper use of this function.

Returnvalues:
string clipboard_string
the content of the clipboard as a string


^ Reaper version 5.95 Ultraschall version 4.00PutMediaItemsToClipboard_MediaItemArray

Lua: boolean retval = ultraschall.PutMediaItemsToClipboard_MediaItemArray(MediaItemArray MediaItemArray)

Puts the items in MediaItemArray into the clipboard.

Returns false in case of an error

Returnvalues:
boolean retval
true, if successful; false, if not

Parameters:
MediaItemArray MediaItemArray
an array with all MediaItems, that shall be put into the clipboard


^ Reaper version 6.02 SWS version 2.10.0.1 Ultraschall version 4.00ToClip

Lua: ToClip(string toclipstring)

Puts a string into clipboard.

\0-characters will be seen as string-termination, so if you want to put strings into clipboard containing them, you need to replace them first or your string might be truncated

Parameters:
string toclipstring
the string, which you want to put into the clipboard


^ Reaper version 5.95 Ultraschall version 4.00ApplyColorTableToItemColors

Lua: boolean retval = ultraschall.ApplyColorTableToItemColors(array ColorTable, integer Spread, MediaItemArray MediaItemArray)

Apply a ColorTable to MediaItems in a MediaItemArray, to colorize MediaItems

ColorTables can be created by CreateColorTable

returns false in case of an error


Returnvalues:
boolean retval
true, adjusting item-colors was successful; false, adjusting item-colors was unsuccessful

Parameters:
array ColorTable
the ColorTable to apply to the MediaItemColors
integer Spread
0, apply ColorTable once; will return false, if fewer colors are in ColorTable available than items in the MediaItemArray
nil or 1, repeat the colors from the ColorTable over and over again over the item; means: if you have 10 items and 5 colors, the colors will fill items 1 to 5 and then again items 6 to 10
2, spread the colors from the ColorTable over all items equally
MediaItemArray MediaItemArray
an array with all the MediaItems to colorize


^ Reaper version 5.95 Ultraschall version 4.00ApplyColorTableToTrackColors

Lua: boolean retval = ultraschall.ApplyColorTableToTrackColors(array ColorTable, integer Spread, integer StartTrack, integer EndTrack)

Apply a ColorTable to Tracks, to colorize MediaTracks

ColorTables can be created by CreateColorTable

returns false in case of an error


Returnvalues:
boolean retval
true, adjusting track-colors was successful; false, adjusting track-colors was unsuccessful

Parameters:
array ColorTable
the ColorTable to apply to the MediaTrackColors
integer Spread
0, apply ColorTable once; will return false, if fewer colors are in ColorTable available than tracks in the project
nil or 1, repeat the colors from the ColorTable over and over again over the tracks; means: if you have 10 tracks and 5 colors, the colors will fill track 1 to 5 and then again track 6 to 10
2, spread the colors from the ColorTable over all tracks equally
integer StartTrack
the first track to colorize; nil, to use the first track in project
integer EndTrack
the last track to colorize; nil, to use the last track in project


^ Reaper version 5.95 Ultraschall version 4.00ChangeColorBrightness

Lua: integer red, integer green, integer blue, boolean retval = ultraschall.ChangeColorBrightness(integer r, integer g, integer b, integer bright_r, optional integer bright_g, optional integer bright_b)

Changes brightness of a colorvalue. If you only set brightr without setting brightg and brightb, then the value for brightr will affect g and b as well.

If a color-value becomes >255 or <0, it will be set to 255 or 0 respectively.

returns color-value 0,0,0 and retval=false in case of an error


Returnvalues:
integer red
the new red-value
integer green
the new green-value
integer blue
the new blue-value
boolean retval
true, color-calculation was successful; false, color-calculation was unsuccessful

Parameters:
integer r
the red-value to be changed
integer g
the green-value to be changed
integer b
the blue-value to be changed
integer bright_r
the change in brightness for the red-color; positive, brighter; negative, darker
optional integer bright_g
the change in brightness for the green-color; positive, brighter; negative, darker; if nil, value in bright_r will be used
optional integer bright_b
the change in brightness for the blue-color; positive, brighter; negative, darker; if nil, value in bright_r will be used


^ Reaper version 5.95 Ultraschall version 4.00ChangeColorContrast

Lua: integer red, integer green, integer blue, boolean retval = ultraschall.ChangeColorContrast(integer r, integer g, integer b, integer Minimum_r, optional integer Maximum_r, optional integer Minimum_g, optional integer Maximum_g, optional integer Minimum_b, optional integer Maximum_b)

Changes contrast of a colorvalue.

Minimum will set the new minimal, Maximum will set the new maximum-brightness-level. If you set Minimum to 0 and Maximum to 255, contrast will not change.

The lower you set Minimum/Maximum, the darker it becomes; the higher, the brighter it becomes. The farther away Minimum is from Maximum, the stronger the contrast becomes; the closer Minimum is to Maximum, the weaker the contrast becomes.

If you only set Minimum_r and Maximum_r, then these values will be applied to g and b too.

If you omit/set to nil a Maximum-value; it's default value will be 255.

If a color-value becomes >255 or <0, it will be set to 255 or 0 respectively.

returns color-value 0,0,0 and retval=false in case of an error


Returnvalues:
integer red
the new red-value
integer green
the new green-value
integer blue
the new blue-value
boolean retval
true, color-calculation was successful; false, color-calculation was unsuccessful

Parameters:
integer r
the red-value to be changed
integer g
the green-value to be changed
integer b
the blue-value to be changed
integer Minimum_r
the new minimum brightness of the contrast-range of the red-color
optional integer Maximum_r
the new maximum brightness of the contrast-range of the red-color; if nil, it will be seen as 255
optional integer Minimum_g
the new minimum brightness of the contrast-range of the green-color; if nil, it will use the value of Minimum_r
optional integer Maximum_g
the new maximum brightness of the contrast-range of the green-color; if nil, it will be seen as 255
optional integer Minimum_b
the new minimum brightness of the contrast-range of the blue-color; if nil, it will use the value of Minimum_r
optional integer Maximum_b
the new maximum brightness of the contrast-range of the blue-color; if nil, it will be seen as 255


^ Reaper version 5.95 Ultraschall version 4.00ChangeColorSaturation

Lua: integer red, integer green, integer blue, number median, boolean retval = ultraschall.ChangeColorSaturation(integer r, integer g, integer b, integer delta)

Changes saturation of a colorvalue by delta.

If a color-value becomes >255 or <0, it will be set to 255 or 0 respectively.

returns color-value 0,0,0 and retval=false in case of an error


Returnvalues:
integer red
the new red-value
integer green
the new green-value
integer blue
the new blue-value
number median
the median-value, calculated from the the old red, green and blue, values (red+green+blue)/3, which is the basis for the brightness of the unsaturated value
boolean retval
true, color-calculation was successful; false, color-calculation was unsuccessful

Parameters:
integer r
the red-value to be changed
integer g
the green-value to be changed
integer b
the blue-value to be changed
integer delta
the saturation/desaturation-value; negative, desaturates color; positive, saturates color


^ Reaper version 5.52 Ultraschall version 4.00ConvertColor

Lua: integer colorvalue, boolean retval = ultraschall.ConvertColor(integer r, integer g, integer b)

converts r, g, b-values to native-system-color. Works like reaper's ColorToNative, but doesn't need |0x1000000 added.

returns color-value 0, and retval=false in case of an error

Returnvalues:
integer colorvalue
the native-system-color; 0 to 33554431

Parameters:
integer r
the red colorvalue
integer g
the green colorvalue
integer b
the blue colorvalue


^ Reaper version 5.95 Ultraschall version 4.00ConvertColorFromMac

Lua: integer red, integer green, integer blue, boolean retval = ultraschall.ConvertColorFromMac(integer mac_colorvalue)

Converts a native-colorvalue to the correct rgb-color-values for Mac, no matter if you're using Mac, Windows or Linux.

returns 0, 0, 0, false in case of an error

Returnvalues:
integer red
the red-value of the color
integer green
the green-value of the color
integer blue
the blue-value of the color
boolean retval
true, if conversion succeeded; false, if conversion failed

Parameters:
integer mac_colorvalue
the Mac-native-colorvalue


^ Reaper version 5.95 Ultraschall version 4.00ConvertColorFromWin

Lua: integer red, integer green, integer blue, boolean retval = ultraschall.ConvertColorFromWin(integer win_colorvalue)

Converts a native-colorvalue to the correct rgb-color-values for Windows/Linux, no matter if you're using Mac, Windows or Linux.

returns 0, 0, 0, false in case of an error

Returnvalues:
integer red
the red-value of the color
integer green
the green-value of the color
integer blue
the blue-value of the color
boolean retval
true, if conversion succeeded; false, if conversion failed

Parameters:
integer win_colorvalue
the Windows/Linux-native-colorvalue


^ Reaper version 5.52 Ultraschall version 4.00ConvertColorReverse

Lua: integer r, integer g, integer b, boolean retval = ultraschall.ConvertColorReverse(integer colorvalue)

converts a native-system-color to r, g, b-values.

returns 0,0,0,false in case of an error

Returnvalues:
integer r
the red colorvalue
integer g
the green colorvalue
integer b
the blue colorvalue
boolean retval
true, color-conversion was successful; false, color-conversion was unsuccessful

Parameters:
integer colorvalue
the native-system-color; 0 to 33554431


^ Reaper version 5.40 Ultraschall version 4.00ConvertColorToGFX

Lua: number r, number g, number b, number a = ultraschall.ConvertColorToGFX(integer r, integer g, integer b, integer a)

converts red,green,blue,alpha-values from 0-255 range to 0-1 range, so these values can be used by Reaper-Lua's gfx.functions().

supports negative-values up from -255 to +255, so you can use the function as well for subtraction of colorvalues.

returns nil in case of error

Returnvalues:
number r
the converted red-value between -1 and +1; nil in case of error
number g
the converted green-value between -1 and +1
number b
the converted blue-value between -1 and +1
number a
the converted alpha-value between -1 and +1

Parameters:
integer r
the red-color-value between -255 and +255
integer g
the green-color-value between -255 and +255
integer b
the blue-color-value between -255 and +255
integer a
the alpha-color-value between -255 and +255


^ Reaper version 5.95 Ultraschall version 4.00ConvertColorToMac

Lua: integer mac_colorvalue, boolean retval = ultraschall.ConvertColorToMac(integer red, integer green, integer blue)

Converts a colorvalue to the correct-native-colorvalue for Mac, no matter if you're using Mac, Windows or Linux.

returns 0, false in case of an error

Returnvalues:
integer mac_colorvalue
the Mac-native-colorvalue
boolean retval
true, if conversion succeeded; false, if conversion failed

Parameters:
integer red
the red-value of the color
integer green
the green-value of the color
integer blue
the blue-value of the color


^ Reaper version 5.95 Ultraschall version 4.00ConvertColorToWin

Lua: integer win_linux_colorvalue, boolean retval = ultraschall.ConvertColorToWin(integer red, integer green, integer blue)

Converts a colorvalue to the correct-native-colorvalue for Windows/Linux, no matter if you're using Mac, Windows or Linux.

returns 0, false in case of an error

Returnvalues:
integer win_linux_colorvalue
the Windows/Linux-native-colorvalue
boolean retval
true, if conversion succeeded; false, if conversion failed

Parameters:
integer red
the red-value of the color
integer green
the green-value of the color
integer blue
the blue-value of the color


^ Reaper version 5.40 Ultraschall version 4.00ConvertGFXToColor

Lua: integer r, integer g, integer b, integer a = ultraschall.ConvertGFXToColor(number r, number g, number b, number a)

converts red,green,blue,alpha-values from 0-1 range to 0-255 range, so these values can be used by Reaper's normal color-value-functions.

supports negative-values up from -1 to +1, so you can use the function as well for subtraction of colorvalues.

returns nil in case of error

Returnvalues:
integer r
the red-color-value between -255 and +255
integer g
the green-color-value between -255 and +255
integer b
the blue-color-value between -255 and +255
integer a
the alpha-color-value between -255 and +255

Parameters:
number r
the converted red-value between -1 and +1; nil in case of error
number g
the converted green-value between -1 and +1
number b
the converted blue-value between -1 and +1
number a
the converted alpha-value between -1 and +1


^ Reaper version 5.95 Ultraschall version 4.00CreateColorTable

Lua: array ColorTable = ultraschall.CreateColorTable(integer startr, integer startg, integer startb, integer endr, integer endg, integer endb, integer number_of_steps)

Returns a colortable to be used by color-graphics-functions.

The colorvalue for start and end can be 0 to 255 or the other way round 255 to 0

Can be used by ApplyColorTableToTrackColors

returns nil in case of an error


Returnvalues:
array ColorTable
a colortable for the colors with the number of steps of your choice;
each indexentry holds entries "r"(0-255), "g"(0-255), "b"(0-255), "nativecolor" and "gfxr"(0-1), "gfxg"(0-1), "gfxb"(0-1).

Parameters:
integer startr
start redvalue, between 0 and 255
integer startg
start greenvalue, between 0 and 255
integer startb
start bluevalue, between 0 and 255
integer endr
end redvalue, between 0 and 255
integer endg
end greenvalue, between 0 and 255
integer endb
end bluevalue, between 0 and 255
integer number_of_steps
the number of steps from the lowest to the highest r,g,b-color start/end-values


^ Reaper version 5.95 Ultraschall version 4.00CreateSonicRainboomColorTable

Lua: array ColorTable = ultraschall.CreateSonicRainboomColorTable()

Returns a colortable in Ultraschall's standard-trackcolor-setting "Sonic Rainboom"-style.

Can be used by ApplyColorTableToTrackColors


Returnvalues:
array ColorTable
a colortable with all values for Ultraschall's track-color "Sonic Rainboom"


^ Reaper version 5.95 Ultraschall version 4.00IsValidColorTable

Lua: boolean retval = ultraschall.IsValidColorTable(array ColorTable)

Checks for valid color-tables.

returns false in case of an error


Returnvalues:
boolean retval
true, if it's a valid ColorTable; false, if it's not a valid ColorTable

Parameters:
array ColorTable
a table to check for being a valid ColorTable


^ Reaper version 5.40 Ultraschall version 4.00RGB2Grayscale

Lua: integer graycolor = ultraschall.RGB2Grayscale(integer red, integer green, integer blue)

converts rgb to a grayscale value. Works native on Mac as well on Windows, no color conversion needed.

returns nil in case of an error

Returnvalues:
integer graycolor
the gray color-value, generated from red,blue and green.

Parameters:
integer red
red-value between 0 and 255.
integer green
red-value between 0 and 255.
integer blue
red-value between 0 and 255.


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigActionMenu

Lua: integer retval = ultraschall.GetSetConfigActionMenu(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Show recent actions"-entry, as set in the Actions-menu.
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "actionmenu", as well as the reaper.ini-entry "REAPER -> actionmenu"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, don't show recent actions - unchecked
1, show recent actions - checked

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, don't show recent actions - unchecked
1, show recent actions - checked
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAlwaysAllowKB

Lua: integer retval = ultraschall.GetSetConfigAlwaysAllowKB(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Allow keyboard commands even when mouse-editing"-checkbox, as set in Preferences -> General ->Advanced UI/system tweaks
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "alwaysallowkb", as well as the reaper.ini-entry "REAPER -> alwaysallowkb"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value; 0(don't allow) to 1(allow)

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value; 0 to 1
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAudioCloseTrackWnds

Lua: integer retval = ultraschall.GetSetConfigAudioCloseTrackWnds(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Allow snap grid/track envelope/routing windows to stay open"-checkbox in Preferences -> General -> Advanced UI/system tweaks.  
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "autoclosetrackwnds", as well as the reaper.ini-entry "REAPER -> autoclosetrackwnds"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, it is allowed(on) - checked  
1, it is not allowed(off) - unchecked  

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, it is allowed(on) - checked  
1, it is not allowed(off) - unchecked  
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAllStereoPairs

Lua: integer retval = ultraschall.GetSetConfigAllStereoPairs(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Show non-standard stereo channel pairs(i.e Input2/Input3 etc)"-checkbox in the Channel naming/mapping-section, as set in Preferences -> Audio
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "allstereopairs", as well as the reaper.ini-entry "REAPER -> allstereopairs"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, don't show non standard stereo channel pairs(off) - unchecked
1, show non standard stereo channel pairs(on) - checked

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, don't show non standard stereo channel pairs(off) - unchecked
1, show non standard stereo channel pairs(on) - checked
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAudioCloseStop

Lua: integer retval = ultraschall.GetSetConfigAudioCloseStop(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Close audio device when stopped and active(less responsive)"-checkbox, as set in Preferences -> Audio  
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "audioclosestop", as well as the reaper.ini-entry "REAPER -> audioclosestop"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAudioThreadPr

Lua: integer retval = ultraschall.GetSetConfigAudioThreadPr(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Audio thread priority"-dropdownlist, as set in Preferences -> Device  
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "audiothreadpr", as well as the reaper.ini-entry "REAPER -> audiothreadpr"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
-1, ASIO Default / MMCSS Pro Audio / Time Critical  
0, Normal  
1, Above normal  
2, Highest  
3, Time Critical  
4, MMCSS / Time Critical  

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
-1, ASIO Default / MMCSS Pro Audio / Time Critical  
0, Normal  
1, Above normal  
2, Highest  
3, Time Critical  
4, MMCSS / Time Critical  
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigApplyFXTail

Lua: integer retval = ultraschall.GetSetConfigApplyFXTail(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Tail length when using Apply FX to items"-inputbox in milliseconds, as set in Preferences -> Media
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "applyfxtail", as well as the reaper.ini-entry "REAPER -> applyfxtail"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value; 0 to 2147483647

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value; 0 to 2147483647
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAutoMute

Lua: integer retval = ultraschall.GetSetConfigAutoMute(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Automute-dropdownlist in the section Mute"-settings, as set in Preferences -> Mute/Solo
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "automute", as well as the reaper.ini-entry "REAPER -> automute"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, No automatic muting  
1, Automatically mute master track  
2, Automatically mute any track  

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, No automatic muting  
1, Automatically mute master track  
2, Automatically mute any track  
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAutoMuteFlags

Lua: integer retval = ultraschall.GetSetConfigAutoMuteFlags(boolean set, integer setting, boolean persist)

Sets the "Reset on playback start"-checkbox in section Mute-settings, as set in Preferences -> Mute/Solo  
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "automuteflags", as well as the reaper.ini-entry "REAPER -> automuteflags"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, Reset on playback start(on) - checked  
1, Reset on playback start(off) - unchecked  

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, Reset on playback start(on) - checked  
1, Reset on playback start(off) - unchecked  
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAutoSaveInt

Lua: integer retval = ultraschall.GetSetConfigAutoSaveInt(boolean set, integer setting, boolean persist)

Sets the "Every x minutes"-inputbox from the Project saving-section, as set in Preferences -> Project.
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "autosaveint", as well as the reaper.ini-entry "REAPER -> autosaveint"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0 to 2147483647; in seconds; higher values become negative

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0 to 2147483647 in seconds
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAutoSaveMode

Lua: integer retval = ultraschall.GetSetConfigAutoSaveMode(boolean set, integer setting, boolean persist)

Sets the "Every x minutes"-dropdownlist from the Project saving-section, as set in Preferences -> Project.
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "autosavemode", as well as the reaper.ini-entry "REAPER -> autosavemode"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, when not recording  
1, when stopped  
2, any time  

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, when not recording  
1, when stopped  
2, any time  
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAdjRecLat

Lua: integer retval = ultraschall.GetSetConfigAdjRecLat(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Use audio driver reported latency"-checkbox, as set in Preferences -> Recording
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "adjreclat", as well as the reaper.ini-entry "REAPER -> adjreclat"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, don't use audio driver reported latency(off) - unchecked
1, don't use audio driver reported latency(on) - checked

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
0, don't use audio driver reported latency(off) - unchecked
1, don't use audio driver reported latency(on) - checked
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAdjRecManLat

Lua: integer retval = ultraschall.GetSetConfigAdjRecManLat(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Output manual offset-samples"-inputbox, as set in Preferences -> Recording
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "adjrecmanlat", as well as the reaper.ini-entry "REAPER -> adjrecmanlat"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value; 0 to 2147483647; in samples

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value; 0 to 2147483647; in samples
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAdjRecManLatIn

Lua: integer retval = ultraschall.GetSetConfigAdjRecManLatIn(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Input manual offset-samples"-inputbox, as set in Preferences -> Recording
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "adjrecmanlatin", as well as the reaper.ini-entry "REAPER -> adjrecmanlatin"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAcidImport

Lua: integer retval = ultraschall.GetSetConfigAcidImport(boolean set, integer setting, boolean persist)

Gets/Sets the value of "When importing media"-dropdownlist, as set in the Media with embedded tempo information-section in Preferences -> Video/REX/Misc
To keep the setting after restart of Reaper, set persist=true

This alters the configuration-variable "acidimport", as well as the reaper.ini-entry "REAPER -> acidimport"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
-1, an error occured
0, Adjust media to project tempo
1, Import media at source tempo
2, Always prompt when importing media with embedded tempo

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the current/new setting-value
-1, an error occured
0, Adjust media to project tempo
1, Import media at source tempo
2, Always prompt when importing media with embedded tempo
boolean persist
true, this setting will be kept after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAfxCfg

Lua: integer retval = ultraschall.GetSetConfigAfxCfg(boolean set, integer setting, boolean persist)

Gets/Sets the value of the audioformat for "Apply FX, Glue, Freeze, etc", as set in the Project Settings->Media-dialog
Only sets the format, not the individual format-settings(like bitrate, etc)!
To keep the setting for new projects as standard-setting after restart of Reaper, set persist=true

This alters the configuration-variable "afxcfg", as well as the reaper.ini-entry "REAPER -> afxcfg"

returns -1 in case of an error

Returnvalues:
integer retval
the current/newly set audioformat
0, not set yet
1179012432, Video (ffmpeg/libav encoder)
1195984416, Video (GIF)
1279477280, Video (LCF)
1332176723, OGG Opus
1634297446, AIFF
1684303904, DDP
1718378851, FLAC
1769172768, Audio CD Image(CUE/BIN format)
1836069740, MP3 (encoder by LAME project)
1869047670, OGG Vorbis
2002876005, WAV
2004250731, WavPack lossless compressor

Parameters:
boolean set
true, set a new value; false, return the current value
integer setting
the new set audioformat
1179012432, Video (ffmpeg/libav encoder)
1195984416, Video (GIF)
1279477280, Video (LCF)
1332176723, OGG Opus
1634297446, AIFF
1684303904, DDP
1718378851, FLAC
1769172768, Audio CD Image(CUE/BIN format)
1836069740, MP3 (encoder by LAME project)
1869047670, OGG Vorbis
2002876005, WAV
2004250731, WavPack lossless compressor
boolean persist
true, this setting will be standard-setting for new projects after restart of Reaper; false, setting will be lost after exiting Reaper


^ Reaper version 5.941 SWS version 2.9.7 Ultraschall version 4.00GetStartNewFileRecSizeState

Lua: boolean start_new_files, boolean offset_file_switches, integer max_rec_size = ultraschall.GetStartNewFileRecSizeState()

Returns, if Reaper shall start a file after a specified amount of MegaBytes as well, if the fileswitches shall be offset when multitrack-recording and the maximum filesize before starting a new file.

see SetStartNewFileRecSizeState for setting the current settings.

Returnvalues:
boolean start_new_files
true, Reaper starts a new file, when a recorded file reaches max_rec_size; false, files are as long until recording stops
boolean offset_file_switches
true, When recording multiple tracks, offset file switches for better performance; false, don't offset file-switches
integer max_rec_size
the maximum length of a recorded file in MegaBytes, before Reaper shall start a new file; only applied when When recording multiple tracks, offset file switches for better performance=true


^ Reaper version 5.941 SWS version 2.9.7 Ultraschall version 4.00SetStartNewFileRecSizeState

Lua: boolean retval = ultraschall.SetStartNewFileRecSizeState(boolean start_new_files, boolean offset_file_switches, integer maxrecsize, boolean persist)

Sets, if Reaper shall start a file after a specified amount of MegaBytes as well, if the fileswitches shall be offset when multitrack-recording and the maximum filesize before starting a new file.

see GetStartNewFileRecSizeState for getting the current settings.

Returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
boolean start_new_files
true, Reaper starts a new file, when a recorded file reaches max_rec_size; false, files are as long until recording stops
boolean offset_file_switches
true, When recording multiple tracks, offset file switches for better performance; false, don't offset file-switches
integer max_rec_size
the maximum length of a recorded file in MegaBytes, before Reaper shall start a new file; only applied when When recording multiple tracks, offset file switches for better performance=true
boolean persist
true, set the setting to reaper.ini so it persists after restarting Reaper; false, set it only for the time, until Reaper is restarted


^ Reaper version 5.95 SWS version 2.9.7 Ultraschall version 4.00GetSetConfigAudioPrShift

Lua: integer retval = ultraschall.GetSetConfigAudioPrShift(boolean set, integer setting, boolean persist)

Gets/Sets the value of "Preserve pitch in audio items when changing master playrate", as set in the contextmenu of the master-playrate in the transport-area as well as toggled by action 40671(all sections)
This is a project-setting. That means, setting persist to true will have an effect on new projects create, but only after you restarted Reaper!

This alters the configuration-variable "audioprshift", as well as the reaper.ini-entry "REAPER -> audioprshift"

returns -1 in case of an error

Returnvalues:
integer retval
the current/new setting-value
0, don't preserve pitch - unchecked
1, preserve pitch - checked

Parameters:
boolean set
true, set a new value; false, return the current value
0, don't preserve pitch - unchecked
1, preserve pitch - checked
integer setting
the current/new setting-value
boolean persist
true, this setting will be kept for new projects, but only after restart of Reaper; false, old standard-project-setting will be kept


^ Reaper version 5.40 Ultraschall version 4.00CountIniFileExternalState_key

Lua: integer keyscount = ultraschall.CountIniFileExternalState_key(string section, string ini_filename_with_path)

Count external-state-keys within a specific section, in a ini_filename_with_path.

Returns -1, if file does not exist.

Returnvalues:
integer keyscount
number of keys with section within an ini-configuration-file

Parameters:
string section
the section within the ini-filename
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00CountIniFileExternalState_sec

Lua: integer sectioncount = ultraschall.CountIniFileExternalState_sec(string ini_filename_with_path)

Count external-state-[sections] from an ini-configurationsfile.

Returns -1, if the file does not exist.

Returnvalues:
integer sectioncount
number of sections within an ini-configuration-file

Parameters:
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00CountKeysByPattern

Lua: integer number_of_keys, string sections_and_keys = ultraschall.CountKeysByPattern(string pattern, string ini_filename_with_path)

Counts the number of keys within an ini-file, that fit a specific pattern.

Uses "pattern"-string to determine, how often a key with a certain pattern exists. Good for keys, that have a number in them, like key1, key2, key3.
Returns the number of keys, that include the pattern, as well as a string with all [sections] that contain keys= with a pattern, separated by a , i.e. [section1],key1=,key2=,key3=,[section2],key1=,key4=

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns -1, in case of an error.

Returnvalues:
integer number_of_keys
the number of keys, that fit the pattern
string sections_and_keys
a string, like: [section1],Key1=,Key2=,Key3=[section2],Key7=

Parameters:
string pattern
the pattern itself. Case sensitive.
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00CountSectionsByPattern

Lua: integer number_of_sections, string sectionnames = ultraschall.CountSectionsByPattern(string pattern, string ini_filename_with_path)

Counts the number of sections within an ini-file, that fit a specific pattern.

Uses "pattern"-string to determine, how often a section with a certain pattern exists. Good for sections, that have a number in them, like [section1], [section2], [section3].
Returns the number of sections, that include that pattern as well as a string, that includes the names of all such sections, separated by a comma.

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns -1, in case of an error.

Returnvalues:
integer number_of_sections
the number of sections, that fit the pattern
string sectionnames
a string, like: [section1],[section8],[section99]

Parameters:
string pattern
the pattern itself. Case sensitive.
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00CountValuesByPattern

Lua: integer number_of_values, string sections_and_keys = ultraschall.CountValuesByPattern(string pattern, string ini_filename_with_path)

Counts the number of values within an ini-file, that fit a specific pattern.

Uses "pattern"-string to determine, how often a value with a certain pattern exists. Good for values, that have a number in them, like value1, value2, value3
Returns the number of values, that include that pattern as well as a string, that contains the [sections] and the keys= and values , the latter that contain the pattern, separated by a comma
e.g. [section1], key1=, value, key4=, value, [section4], key2=, value

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns -1, in case of an error.

Returnvalues:
integer number_of_values
the number of values, that fit the pattern
string sections_keys_values
a string, like: [section1],key1=,value,key4=,value,[section4],key2=,value

Parameters:
string pattern
the pattern itself. Case sensitive.
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00EnumerateIniFileExternalState_key

Lua: string keyname = ultraschall.EnumerateIniFileExternalState_key(string section, integer number, string ini_filename_with_path)

Returns the numberth key within a section in an ini_filename_with_path.

Returns nil, in case of an error.

Returnvalues:
string keyname
the name of the numberth key within section in the ini-file

Parameters:
string section
the name of the section
integer number
the number of the key within a section within the ini-filename, with 1 for the first key in the section
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 Ultraschall version 4.00EnumerateIniFileExternalState_sec

Lua: string sectionname = ultraschall.EnumerateIniFileExternalState_sec(integer number_of_section, string ini_filename_with_path)

Returns the numberth section in an ini_filename_with_path.

Returns nil, in case of an error.

Returnvalues:
string sectionname
the name of the numberth section in the ini-file

Parameters:
integer number_of_section
the section within the ini-filename; 1, for the first section
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00EnumerateKeysByPattern

Lua: string keyname = ultraschall.EnumerateKeysByPattern(string pattern, string section, integer id, string ini_filename_with_path)

Returns the numberth key within a section in an ini-file, that fits the pattern, e.g. the third key containing "hawaii" in it.

Uses "pattern"-string to determine if a key contains a certain pattern. Good for keys, that have a number in them, like key1=, key2=, key3=
Returns the key that includes that pattern as a string, numbered by id.

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns nil, in case of an error.

Returnvalues:
string keyname
a string, that contains the keyname

Parameters:
string pattern
the pattern itself. Case sensitive.
string section
the section, in which to look for the key
integer id
the number of key, that contains pattern
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00EnumerateSectionsByPattern

Lua: string sectionname = ultraschall.EnumerateSectionsByPattern(string pattern, integer id, string ini_filename_with_path)

Returns the numberth section within an ini-file, that fits the pattern, e.g. the third section containing "hawaii" in it.

Uses "pattern"-string to determine if a section contains a certain pattern. Good for sections, that have a number in them, like section1, section2, section3
Returns the section that includes that pattern as a string, numbered by id.

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns nil, in case of an error.

Returnvalues:
string sectionname
a string, that contains the sectionname

Parameters:
string pattern
the pattern itself. Case sensitive.
integer id
the number of section, that contains pattern
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00EnumerateValuesByPattern

Lua: string value, string keyname = ultraschall.EnumerateValuesByPattern(string pattern, string section, string id, string ini_filename_with_path)

Returns the numberth value(and it's accompanying key) within a section in an ini-file, that fits the pattern, e.g. the third value containing "hawaii" in it.

Uses "pattern"-string to determine if a value contains a certain pattern. Good for values, that have a number in them, like value1, value2, value3
Returns the value that includes that pattern as a string, numbered by id, as well as it's accompanying key.

Pattern can also contain patterns for pattern matching. Refer the LUA-docs for pattern matching.
i.e. characters like ^$()%.[]*+-? must be escaped with a %, means: %[%]%(%) etc

Returns nil, in case of an error.

Returnvalues:
string value
the value that contains the pattern
string keyname
a string, that contains the keyname

Parameters:
string pattern
the pattern itself. Case sensitive.
string section
the section, in which to look for the key
integer id
the number of key, that contains pattern
string ini_filename_with_path
filename of the ini-file


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00GetIniFileExternalState

Lua: string value = ultraschall.GetIniFileExternalState(string section, string key, string ini_filename_with_path)

Gets an external state from ini_filename_with_path. Returns -1, if the file does not exist or parameters are invalid.

Returnvalues:
integer entrylength
the length of the returned value
string value
the value stored in a section->key in a configuration-file

Parameters:
string section
section of the external state
string key
key of the external state. No = allowed!
string filename_with_path
filename of the ini-file


^ Reaper version 5.965 Ultraschall version 4.00GetIniFileValue

Lua: integer length_of_value, string value = ultraschall.GetIniFileValue(string section, string key, string errval, string inifile)

Gets a value from a key of an ini-file

returns -1 in case of an error

Returnvalues:
integer length_of_value
the length of the value in bytes
string value
the value from the key-value-pair

Parameters:
string section
the section, in which the key-value-pair is located
string key
the key whose value you want
string errval
an errorvalue, which will be shown, if key-value-store doesn't exist
string inifile
the ini-file, from which you want to retrieve the key-value-store


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00SetIniFileExternalState

Lua: boolean retval = ultraschall.SetIniFileExternalState(string section, string key, string value, string ini_filename_with_path)

Sets an external state into ini_filename_with_path. Returns false, if it doesn't work.

Returnvalues:
boolean retval
true, if setting the state was successful; false, if setting was unsuccessful

Parameters:
string section
section of the external state. No = allowed!
string key
key of the external state. No = allowed!
string value
value for the key
string filename_with_path
filename of the ini-file


^ Reaper version 5.965 SWS version 2.10.0.1 Ultraschall version 4.00SetIniFileValue

Lua: integer retval = ultraschall.SetIniFileValue(string section, string key, string value, string inifile)

Sets a value of a key in an ini-file

returns -1 in case of an error

Returnvalues:
integer retval
-1, in case of an error; 1, in case of success

Parameters:
string section
the section, in which the key-value-pair is located
string key
the key whose value you want to change
string value
the new value for this key-value-pair
string inifile
the ini-file, in which you want to set the key-value-store


^ Reaper version 5.40 Ultraschall version 4.2CountKBIniActions

Lua: integer actions = ultraschall.CountKBIniActions(string filename_with_path)

Count the number of "ACT"-Actions of the Reaper-kb.ini-file.
Returns -1, if no such file exists.

Returnvalues:
integer actions
number of actions in the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.2CountKBIniKeys

Lua: integer keys = ultraschall.CountKBIniKeys(string filename_with_path)

Count the number of "KEY"-Keybindings of the Reaper-kb.ini-file.
Returns -1, if no such file exists.

Returnvalues:
integer keys
number of keys in the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.2CountKBIniScripts

Lua: integer scripts = ultraschall.CountKBIniScripts(string filename_with_path)

Count the number of "SCR"-Scripts of the Reaper-kb.ini-file.
Returns -1, if no such file exists.

Returnvalues:
integer scripts
number of scripts in the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.00DeleteKBIniActions

Lua: boolean retval = ultraschall.DeleteKBIniActions(string filename_with_path, integer idx)

Deletes an "ACT"-action of a reaper-kb.ini.
Returns true/false when deleting worked/didn't work.

Needs a restart of Reaper for this change to take effect!

Returnvalues:
boolean retval
true, if deleting worked, false if it didn't

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer idx
indexnumber of the action within the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.00DeleteKBIniKeys

Lua: boolean retval = ultraschall.DeleteKBIniKeys(string filename_with_path, integer idx)

Deletes a "KEY"-keybinding of a reaper-kb.ini.
Returns true/false when deleting worked/didn't work.

Needs a restart of Reaper for this change to take effect!

Returnvalues:
boolean retval
true, if deleting worked, false if it didn't

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer idx
indexnumber of the keybinding within the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.00DeleteKBIniScripts

Lua: boolean retval = ultraschall.DeleteKBIniScripts(string filename_with_path, integer idx)

Deletes an "SCR"-script of a reaper-kb.ini.
Returns true/false when deleting worked/didn't work.

Needs a restart of Reaper for this change to take effect!

Returnvalues:
boolean retval
true, if deleting worked, false if it didn't

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer idx
indexnumber of the script within the reaper-kb.ini


^ Reaper version 6.17 Ultraschall version 4.2GetActionCommandIDByFilename

Lua: string ActionCommandID = ultraschall.GetActionCommandIDByFilename(string searchfilename, integer searchsection, optional boolean case_sensitive)

Returns the action-command-id of a script by its filename, as registered in the reaper-kb.ini.

Important: scripts in subfolders of Scripts must be written with their full path. \ and / are supported as folder-separators.
Setting case_sensitive=false will return the action-command-id of the first script matching the filename, when you don't know the exact case-sensitivity.
Keep in mind, that on Linux, camelcase can mean different filenames. So Prototype.lua and prototype.lua are different files on Linux, when they exist together.
Keep that in mind or you risk finding the wrong ActionCommandID.

Returns nil in case of an error

Returnvalues:
string ActionCommandID
the actioncommand-id of the scriptfile; "", if no such file is installed; nil, in case of an error

Parameters:
string searchfilename
the filename(plus path, if needed) of the script, whose ActionCommandID you want to have.
integer section
the section, in which the file is stored
0, Main,
100, Main (alt recording),
32060, MIDI Editor,
32061, MIDI Event List Editor,
32062, MIDI Inline Editor,
32063, Media Explorer.
optional boolean case_sensitive
true or nil, search for filename on a case-sensitive base; false, case-sensitivity in filename is ignored


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniActions

Lua: integer consolidate, integer section, string ActionCommandID, string description, string ActionsToBeExecuted = ultraschall.GetKBIniActions(string filename_with_path, integer idx)

Get the states of "ACT"-Action number idx. Returns consolidate, section, ActionCommandID, description, ActionsToBeExecuted.
Returns -1, if no such entry or file exists.

Returnvalues:
integer consolidate
consolidate-state
1 consolidate undo points,
2 show in Actions-Menu,
3 consolidate undo points AND show in Actions Menu;
maybe 4 and higher?    
integer section
the section, in which this action is executed
0 - Main
1 - action stays invisible but is kept, if Reaper rewrites the reaper-kb.ini. Menu-buttons with this action associated appear but don't work.
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer    
string ActionCommandID
the ActionCommandID given to this Action
string description
the description of this action
string ActionsToBeExecuted
the actions that are run, the ActionCommandIDs beginning with _, multiple ActionCommandIDs are separated by whitespaces

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
integer idx
the number of the action to get, beginning with 1 for the first one


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniActionsID_ByActionCommandID

Lua: string retval, integer indexcount, table indices = ultraschall.GetKBIniActionsID_ByActionCommandID(filename_with_path, ActionCommandID)

Returns the indexnumber(s) of actions by ActionCommandIDs within a reaper-kb.ini.
Returns -1, if no such entry or file exists.

Returnvalues:
string retval
the ids of actions with ActionCommandID, separated by a ,
integer indexcount
the number of indices found
table indices
a table with all indices found

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
string ActionCommandID
the ActionCommandID


^ Reaper version 5.40 Ultraschall version 4.00GetKBIniFilepath

Lua: string kb_ini_path = ultraschall.GetKBIniFilepath()

Returns the path and filename of the Reaper-kb.ini-file.

Returnvalues:
string kb_ini_path
path and filename of the reaper-kb.ini


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniKeys

Lua: integer keytype_modifier_midichan, integer key_midinote, string ActionCommandID, integer section = ultraschall.GetKBIniKeys(string filename_with_path, integer idx)

Get the states of "KEY"-Keybinding-number idx, for MIDI/Key-bindings. Returns keytype_modifier_midichan, key_midinote, ActionCommandID, section.

For a detailed description in how KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.

Returns -1, if no such entry or file exists.
Does not return OSC-keybindings, as they are stored in OSC/reaper-osc-actions.ini !
returns -1 in case of an error

Returnvalues:
integer keytype_modifier_midichan
Type of Keytype, modifier or midichannel
For a detailed description in how keytype/modifier in KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.
integer key_midinote
the key(like ASCII-Codes) or midinote.
For a detailed description in how key/midinotes in KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.    
string ActionCommandID
the ActionCommandID associated with this shortcut.
integer section
the section, in which this shortcut is used
0 - Main
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
integer idx
the number of the action to get, beginning with 1 for the first one


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniKeys_ByActionCommandID

Lua: string retval, integer indexcount, table indices = ultraschall.GetKBIniKeys_ByActionCommandID(filename_with_path, ActionCommandID)

Returns the indexnumber(s) of keys by ActionCommandIDs within a reaper-kb.ini.
Returns nil, if no such entry or file exists.

Returnvalues:
string retval
the ids of keys with ActionCommandID, separated by a ,
integer indexcount
the number of indices found
table indices
a table with all indices found

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
string ActionCommandID
the ActionCommandID


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniScripts

Lua: integer terminateinstance, integer section, string ActionCommandID, string description, string scriptfile = ultraschall.GetKBIniScripts(string filename_with_path, integer idx)

Get the states of "SCR"-Scripts number idx. Returns terminateinstance, section, ActionCommandID, description, scriptfile.
Returns -1, if no such entry or file exists.

Returnvalues:
integer terminateinstance
the state of terminating instances
4 - Dialogwindow appears(Terminate, New Instance, Abort), if another instance of a given script is started, that's already running
260 - always Terminate Instances, when an instance of the script is already running
516 - always start a New Instance of the script already running
integer section
the section, in which this action is executed
0 - Main
1 - action stays invisible but is kept, if Reaper rewrites the reaper-kb.ini. Menu-buttons with this action associated appear but don't work.
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer    
string ActionCommandID
the ActionCommandID given to this Action
string description
the description of this action
string scriptfile
the filename of the script that shall be run

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
integer idx
the number of the action to get, beginning with 1 for the first one


^ Reaper version 5.40 Ultraschall version 4.2GetKBIniScripts_ByActionCommandID

Lua: string retval, integer indexcount, table indices = ultraschall.GetKBIniScripts_ByActionCommandID(filename_with_path, ActionCommandID)

Returns the indexnumber(s) of scripts by ActionCommandIDs within a reaper-kb.ini.
Returns nil, if no such entry or file exists.

Returnvalues:
string retval
the ids of scripts with ActionCommandID, separated by a ,
integer indexcount
the number of indices found
table indices
a table with all indices found

Parameters:
string filename_with_path
path and filename of the reaper-kb.ini; nil, use current Reaper's reaper-kb.ini
string ActionCommandID
the ActionCommandID


^ Reaper version 6.02 SWS version 2.10.0.1 Ultraschall version 4.00QueryKeyboardShortcutByKeyID

Lua: string Shortcutname = ultraschall.QueryKeyboardShortcutByKeyID(integer modifier, integer key)

Returns the name of the shortcut of the modifier-key-values, as stored in the KEY-entries within the reaper-kb.ini

That way, you can take a KEY-entry from the reaper-kb.ini, like

      KEY 1 65 _Ultraschall_Play_From_Editcursor_Position 0
      
Extract the modifier and key-values(1 and 65 in the example) and pass them to this function.
You will get returned "A" as 1 and 65 is the keyboard-shortcut-code for the A-key.

Only necessary for those, who try to read keyboard-shortcuts directly from the reaper-kb.ini to display them in some way.

returns nil in case of an error

Returnvalues:
string Shortcutname
the actual name of the shortcut, like "A" or "F1" or "Ctrl+Alt+Shift+Win+PgUp".

Parameters:
integer modifier
the modifier value, which is the first one after KEY in a KEY-entry in the reaper-kb.ini-file
integer key
the key value, which is the second one after KEY in a KEY-entry in the reaper-kb.ini-file


^ Reaper version 5.40 Ultraschall version 4.00SetKBIniActions

Lua: boolean retval, integer actionnumber = ultraschall.SetKBIniActions(string filename_with_path, integer consolidate, integer section, string ActionCommandID, string Description, string ActionCommandIDs, boolean replace)

Adds or sets(if it already exists) an "ACT"-action of a reaper-kb.ini.
Returns true/false when adding or setting worked/didn't work, as well as the action-number within the reaper-kb.ini

Needs a restart of Reaper for this change to take effect!

Returnvalues:
boolean retval
true, if adding/setting worked, false if it didn't
integer actionnumber
the entrynumber within the reaper-kb.ini of this action

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer consolidate
consolidation state of this action
1 consolidate undo points,
2 show in Actions-Menu,
3 consolidate undo points AND show in Actions Menu;
maybe 4 and higher?    
integer section
section, in which this action is started
0 - Main
1 - action stays invisible but is kept, if Reaper rewrites the reaper-kb.ini. Menu-buttons with this action associated appear but don't work.
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
string ActionCommandID
the ActionCommandID of this action
string Description
a description for this action
string ActionCommandIDs
the ActionCommandIDs for the actions, that are triggered by this action; unlike CommandID-numbers, every ActionCommandID must begin with _ ; will not be checked vor valid ones!
boolean replace
true if an already existing entry shall be replaced, false if not


^ Reaper version 5.40 Ultraschall version 4.00SetKBIniKeys

Lua: boolean retval, integer keynumber = ultraschall.SetKBIniKeys(string filename_with_path, integer keytype_modifier_midichan, integer key_midinote, string ActionCommandID, integer section, boolean replace)

Adds or sets(if it already exists) a "KEY"-key of a reaper-kb.ini.
Returns true/false when adding or setting worked/didn't work, as well as the keybinding-number within the reaper-kb.ini.
Additional keybindings cannot share the same keytype_modifier_midichan, key_midinote and section at the same time, as every such keybind must be unique.

For a detailed description in how KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.

Does not support OSC-keybindings, as they are stored in OSC/reaper-osc-actions.ini !

Needs a restart of Reaper for this change to take effect!

returns false in case of an error

Returnvalues:
boolean retval
true, if adding/setting worked, false if it didn't
integer scriptnumber
the entrynumber within the reaper-kb.ini of this script

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer keytype_modifier_midichan
Type of Keytype, modifier or midichannel
For a detailed description in how keytype/modifier in KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.
integer key_midinote
the key(like ASCII-Codes) or midinote.
For a detailed description in how key/midinotes in KEY-entries work, refer to Reaper-Filetype-Descriptions.html#Reaper-kb.ini.
string ActionCommandID
the ActionCommandID associated with this shortcut.
integer section
the section, in which this shortcut is used
0 - Main
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
boolean replace
true if an already existing entry shall be replaced, false if not


^ Reaper version 5.40 Ultraschall version 4.00SetKBIniScripts

Lua: boolean retval, integer scriptnumber = ultraschall.SetKBIniScripts(string filename_with_path, integer terminate, integer section, string ActionCommandID, string Description, string Scriptname, boolean replace)

Adds or sets(if it already exists) an "SCR"-script of a reaper-kb.ini.
Returns true/false when adding or setting worked/didn't work, as well as the script-number within the reaper-kb.ini

Needs a restart of Reaper for this change to take effect!

Returnvalues:
boolean retval
true, if adding/setting worked, false if it didn't
integer scriptnumber
the entrynumber within the reaper-kb.ini of this script

Parameters:
string filename_with_path
filename with path for the reaper-kb.ini
integer terminate_state
state of handling mulitple running scripts
4 - Dialogwindow appears(Terminate, New Instance, Abort), if another instance of a given script is started, that's already running
260 - always Terminate Instances, when an instance of the script is already running
516 - always start a New Instance of the script already running
integer section
section, in which this script is started
0 - Main
1 - action stays invisible but is kept, if Reaper rewrites the reaper-kb.ini. Menu-buttons with this action associated appear but don't work.
100 - Main (alt recording)
32060 - MIDI Editor
32061 - MIDI Event List Editor
32062 - MIDI Inline Editor
32063 - Media Explorer
string ActionCommandID
the ActionCommandID of this action
string Description
a description for this script
string Scriptname
the name of the ReaScript, like .lua or .eel or .py
boolean replace
true if an already existing entry shall be replaced, false if not


^ Reaper version 6.02 Ultraschall version 4.00Defer

Lua: boolean retval, optional string defer_identifier = ultraschall.Defer(function func, string deferidentifier, optional integer mode, optional number timer_counter, optional boolean protected)

runs a custom-defer-cycle, which can be individualized.

You can set, how often this defer-cycle shall be run(every x defer-cycle or every x seconds) and even stop the defer-cycle from in- and outside of the script, using the defer_identifier you have given.

To stop such a defer-cycle, use StopDeferCycle, as long as parameter protected is not set to true! Important: make the deferidentifier as unique as possible(using guids or similar stuff) to avoid naming conflicts with other defer-cycles using the same identifier. Otherwise, you risk stopping multiple such defer-loops, when using StopDeferCycle!

For the old Defer1 to Defer20-behavior, try ultraschall.ScriptIdentifier..".defer_scriptXX" as defer-identifier, where XX is a number.

returns false in case of an error (e.g. already 1024 defer-cycles are running in the current script-instance)


Returnvalues:
boolean retval
true, running this defer-cycle was successful; false, it wasn't successful
optional string defer_identifier
if running this defer-cycle was successful, this holds the defer-identifier you've chosen

Parameters:
function func
the function, you would love to defer to
string deferidentifier
an identifier, under which you can access this defer-cycle; make it unique using guids in the name, to avoid name-conflicts!
optional integer mode
0 or nil, just run as regular defer-cycle
1, run the defer-cycle only every timer_counter-cycle
2, run the defer-cycle only every timer_counter-seconds
optional number timer_counter
the timer for the defer-cycle
  mode=1: 1 and higher, the next defer-cycle that shall be used by function func. Use 1 for every cycle, 2 for every second cycle.
              30 cycles are approximately 1 second.
  mode=2: 0 and higher, the amount of seconds to wait, until the function func is run the next time.
optional boolean protected
true, this defer-cycle is protected from being stopped by StopDeferCycle(); false or nil, you can stop this defer-cycle using StopDeferCycle()


^ Reaper version 6.02 Ultraschall version 4.00GetDeferCycleSettings

Lua: integer mode, integer timer_counter = ultraschall.GetDeferCycleSettings(string deferidentifier)

Gets a the mode and timing-settings of a currently running ultraschall.Defer()-cycle

Returns nil in case of failure.

Returnvalues:
integer mode
the timing mode, in which the defer-cycle runs
0, just run as regular defer-cycle
1, run the defer-cycle only every timer_counter-cycle
2, run the defer-cycle only every timer_counter-seconds
number timer_counter
the timer for the defer-cycle
mode=1: 1 and higher, the next defer-cycle that shall be used by function func. Use 1 for every cycle, 2 for every second cycle.
             30 cycles are approximately 1 second.
mode=2: 0 and higher, the amount of seconds to wait, until the function func is run the next time.

Parameters:
string deferidentifier
an identifier, under which you can access this defer-cycle; make it unique using guids in the name, to avoid name-conflicts!


^ Reaper version 5.965 Ultraschall version 4.00GetDeferRunState

Lua: boolean retval = ultraschall.GetDeferRunState(integer deferinstance, optional string scriptidentifier)

returns the run-state of a Ultraschall-defer-loop in a specific scriptinstance

You can either request the runstate of a Defer-deferred-function(set parameter deferinstance to 0).

returns nil in case of an error.


Returnvalues:
boolean retval
true, defer-instance is running; false, defer-instance isn't running

Parameters:
integer deferinstance
0, to use the parameter identifier
optional string identifier
when deferinstance=0 (when using the Defer-function): the identifier of the defer-cycle, you've started with Defer


^ Reaper version 6.02 Ultraschall version 4.00SetDeferCycleSettings

Lua: boolean retval = ultraschall.SetDeferCycleSettings(string deferidentifier, optional integer mode, optional number timer_counter)

Sets the mode and timing settings of a running ultraschall.Defer-instance. You can set its mode and the timer/counter-values, even from a script, which does not run the defer-instance!

Returns false in case of failure.

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
string deferidentifier
an identifier, under which you can access this defer-cycle; make it unique using guids in the name, to avoid name-conflicts!
optional integer mode
the timing mode, in which the defer-cycle runs
nil, reset to the default-settings of the Defer-Cycle
0, just run as regular defer-cycle
1, run the defer-cycle only every timer_counter-cycle
2, run the defer-cycle only every timer_counter-seconds
optional number timer_counter
the timer for the defer-cycle
mode=1: 1 and higher, the next defer-cycle that shall be used by function func. Use 1 for every cycle, 2 for every second cycle.
             30 cycles are approximately 1 second.
mode=2: 0 and higher, the amount of seconds to wait, until the function func is run the next time.


^ Reaper version 5.965 Ultraschall version 4.00StopDeferCycle

Lua: boolean retval = ultraschall.StopDeferCycle(string defer_identifier)

Stops a running ultraschall.Defer-instance of a script-instance.

returns false in case of an error


Returnvalues:
boolean retval
true, stopping this defer-cycle was successful; false, it wasn't successful

Parameters:
string defer_identifier
the identifier of the defer-cycle of a script-instance


^ Reaper version 5.965 Ultraschall version 4.00AddErrorMessage

Lua: boolean retval, integer errorcount = ultraschall.AddErrorMessage(string functionname, string parametername, string errormessage, integer errorcode)

Adds a new errormessage to the Ultraschall-Api-Error-messagesystem. Returns the number of the errormessage.
Intended for your own 3rd party-functions for the API, to give the user more feedback about errors than just a cryptic errorcode.

returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't
integer errorcount
the number of the errormessage within the Ultraschall-Api-Error-messagesystem; nil, if errormessages are suppressed currently

Parameters:
string functionname
the function, where the error happened
string parametername
the parameter, that caused the problem
string errormessage
a longer description of what cause the problem and a hint to a possible solution
integer errorcode
a number, that represents the error-message. Will be -1 by default, if not given.


^ Reaper version 5.95 Ultraschall version 4.00CountErrorMessage_Funcname

Lua: integer number_of_errormessages = ultraschall.CountErrorMessage_Funcname(string functionname)

Returns the number of available errormessages for functionname, existing in the Error-Messaging-System.

returns -1 in case of error

Returnvalues:
integer number_of_errormessages
the number of errormessages functionname has left in the Error-Messaging-System

Parameters:
string functionname
the name of the function, whose error messages you want to count


^ Reaper version 5.40 Ultraschall version 4.00CountErrorMessages

Lua: integer errorcounter = ultraschall.CountErrorMessages()

Returns the current count of errormessages in the system available.

Returnvalues:
integer errorcounter
the number of errormessages currently available in the error-message-system. Includes read and unread ones.


^ Reaper version 5.40 Ultraschall version 4.00DeleteAllErrorMessages

Lua: boolean retval = ultraschall.DeleteAllErrorMessages()

Deletes all error-messages and returns a boolean value.
returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't


^ Reaper version 5.40 Ultraschall version 4.00DeleteErrorMessage

Lua: boolean retval = ultraschall.DeleteErrorMessage(integer errornumber)

Deletes an error-message within the Ultraschall-ErrorMessagesystem.

returns false in case of failure

Returnvalues:
boolean retval
true, if such an error exists; false if it didn't

Parameters:
integer errornumber
the number of the error to delete, beginning with 1. Use CountErrorMessages to get the current number of error-messages.


^ Reaper version 5.40 Ultraschall version 4.00DeleteLastErrorMessage

Lua: boolean retval = ultraschall.DeleteLastErrorMessage()

Deletes the last error-message and returns a boolean value.
returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't


^ Reaper version 5.95 Ultraschall version 4.00GetErrorMessage_Funcname

Lua: integer errorindex, string parametername, string errormessage, integer errorcode = ultraschall.GetErrorMessage_Funcname(string functionname, integer index)

Returns a specific errormessage specified by index, functionname added to the Error-Messaging-System.
Sets read-state of the error-message to the date-time of accessing it.

returns -1 in case of error

Returnvalues:
integer errorindex
the index of the error within the Error-Messaging-System
string parametername
the parameter that produced the problem, or "" if no parameter was involved
string errormessage
the errormessage
integer errorcode
the errorcode the error has

Parameters:
string functionname
the name of the function, whose last error message you want to retrieve
integer index
the index of the error-message for functionname


^ Reaper version 5.40 Ultraschall version 4.00GetLastErrorMessage

Lua: boolean retval, integer errcode, string functionname, string parmname, string errormessage, string lastreadtime, string err_creation_date, string err_creation_timestamp, integer errorcounter = ultraschall.GetLastErrorMessage()

Reads the last error-message stored in the Ultraschall-ErrorMessagesystem.
Returns a boolean value, the functionname, the errormessage, the date and a timestamp of the creation of the errormessage, the unread-status as well as the error-message-number.
returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't
integer errcode
the errorcode of this message, as set by the function that created this errormessage; -1 is default value
string functionname
the name of the function, where the problem happened
string parmname
the parameter, that was used wrong by the programmer; "" if no parameter was involved in this error
string errormessage
the message of the problem with a possible hint to a solution
string readstatus
"unread" if the message hasn't been read yet or a date_time from when the message has been read already
string err_creation_date
the date_time of when the error-message was created
string err_creation_timestamp
the timestamp of when the error-message was created. Usually seconds, since system got started
integer errorcounter
the error-message-number within the Ultraschall-Error-Message-System

Parameters:
integer errornumber
the number of the error, beginning with 1. Use CountErrorMessages to get the current number of error-messages.


^ Reaper version 5.40 Ultraschall version 4.00GetLastErrorMessage2

Lua: boolean retval, array ErrorMessages = ultraschall.GetLastErrorMessage2(integer count, boolean setread)

Returns an array with the last "count" errormessages. 1 for the last, 2 for the last 2, etc.
Set setread to false, if you want to retain the unread status of the error-messages.
returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't
array ErrorMessages
an array, that contains all values for the chosen number of errormessages.
The fields are ErrorMessages[errornumber][x], where x stands for
"errcode" - the errorcode of this function, default is -1
"funcname" - functionname
"parmname" - name of the parameter, that caused the error
"errmsg" - errormessage
"readstate" - readstatus
"date" - errorcreation date_time
"time" - errorcreation timestamp in seconds, usually seconds since computer has been started

Parameters:
integer count
the number of the last few errors, you want to get returned. Use CountErrorMessages to get the current number of error-messages.


^ Reaper version 5.95 Ultraschall version 4.00GetLastErrorMessage_Funcname

Lua: integer errorindex, string parametername, string errormessage, integer errorcode = ultraschall.GetLastErrorMessage_Funcname(string functionname)

Returns the last errormessage, a certain function added to the Error-Messaging-System.
Sets read-state of the error-message to the date-time of accessing it.

returns -1 in case of error

Returnvalues:
integer errorindex
the index of the error within the Error-Messaging-System
string parametername
the parameter that produced the problem, or "" if no parameter was involved
string errormessage
the errormessage
integer errorcode
the errorcode the error has

Parameters:
string functionname
the name of the function, whose last error message you want to retrieve


^ Reaper version 5.40 Ultraschall version 4.1ReadErrorMessage

Lua: boolean retval, integer errcode, string functionname, string parmname, string errormessage, string lastreadtime, string err_creation_date, string err_creation_timestamp = ultraschall.ReadErrorMessage(integer errornumber, optional boolean keep_unread)

Reads an error-message within the Ultraschall-ErrorMessagesystem.
Returns a boolean value, the functionname, the errormessage, the "you've already read this message"-status, the date and a timestamp of the creation of the errormessage.
returns false in case of failure

Returnvalues:
boolean retval
true, if it worked; false if it didn't
integer errcode
the errorcode of this message, as set by the function that created this errormessage; -1 is default value
string functionname
the name of the function, where the problem happened
string parmname
the parameter, that was used wrong by the programmer; "" if no parameter was involved in this error
string errormessage
the message of the problem with a possible hint to a solution
string readstatus
"unread" if the message hasn't been read yet or a date_time from when the message has been read already
string err_creation_date
the date_time of when the error-message was created
string err_creation_timestamp
the timestamp of when the error-message was created. Usually seconds, since system got started

Parameters:
integer errornumber
the number of the error, beginning with 1. Use CountErrorMessages to get the current number of error-messages.
optional boolean keep_unread
true, keeps the message unread; false or nil, sets the readstate of the message


^ Reaper version 5.40 Ultraschall version 4.2SFEM

Lua: requested_error_message = SFEM(optional integer dunk, optional integer target, optional integer message_type)

Displays the first error message in a messagebox, the ReaScript-Console, the clipboard, if error is existing and unread.

Returnvalues:
requested_error_message
the errormessage requested;

Parameters:
optional integer dunk
allows to index the last x'ish message to be returned; nil or 0, the last one; 1, the one before the last one, etc.
optional integer target
the target, where the error-message shall be output to
0 or nil, target is a message box
1, target is the ReaScript-Console
2, target is the clipboard
3, target is a returned string
optional integer message_type
if target is set to 3, you can set, which part of the error-messageshall be returned as returnvalue
nil or 1, returns true, if error has happened, false, if error didn't happen
2, returns the errcode
3, returns the functionname which caused the error
4, returns the parmname which caused the error
5, returns the errormessage
6, returns the lastreadtime
7, returns the err_creation_date
8, returns the err_creation_timestamp      


^ Reaper version 5.40 Ultraschall version 4.1SLEM

Lua: requested_error_message = SLEM(optional integer dunk, optional integer target, optional integer message_type)

Displays the last error message in a messagebox, the ReaScript-Console, the clipboard, if error is existing and unread.

Like ultraschall.ShowLastErrorMessage() but this is easier to type.
Note: written without ultraschall. in the beginning!

Returnvalues:
requested_error_message
the errormessage requested;

Parameters:
optional integer dunk
allows to index the last x'ish message to be returned; nil or 0, the last one; 1, the one before the last one, etc.
optional integer target
the target, where the error-message shall be output to
0 or nil, target is a message box
1, target is the ReaScript-Console
2, target is the clipboard
3, target is a returned string
optional integer message_type
if target is set to 3, you can set, which part of the error-messageshall be returned as returnvalue
nil or 1, returns true, if error has happened, false, if error didn't happen
2, returns the errcode
3, returns the functionname which caused the error
4, returns the parmname which caused the error
5, returns the errormessage
6, returns the lastreadtime
7, returns the err_creation_date
8, returns the err_creation_timestamp      


^ Reaper version 5.965 Ultraschall version 4.00ShowErrorMessagesInReascriptConsole

Lua: ultraschall.ShowErrorMessagesInReascriptConsole(boolean state)

Sets, if errormessages shall be shown in the ReaScript-Console immediately, when they happen.

Will show functionname, parametername, errorcode plus errormessage and the time the error has happened.

Parameters:
boolean state
true, show error-messages in the ReaScript-Console when they happen; false, don't show errormessages


^ Reaper version 5.40 Ultraschall version 4.1ShowLastErrorMessage

Lua: requested_error_message = ultraschall.ShowLastErrorMessage(optional integer dunk, optional integer target, optional integer message_type)

Displays the last error message in a messagebox, the ReaScript-Console, the clipboard, if error is existing and unread.

Returnvalues:
requested_error_message
the errormessage requested;

Parameters:
optional integer dunk
allows to index the last x'ish message to be returned; nil or 0, the last one; 1, the one before the last one, etc.
optional integer target
the target, where the error-message shall be output to
0 or nil, target is a message box
1, target is the ReaScript-Console
2, target is the clipboard
3, target is a returned string
optional integer message_type
if target is set to 3, you can set, which part of the error-messageshall be returned as returnvalue
nil or 1, returns true, if error has happened, false, if error didn't happen
2, returns the errcode
3, returns the functionname which caused the error
4, returns the parmname which caused the error
5, returns the errormessage
6, returns the lastreadtime
7, returns the err_creation_date
8, returns the err_creation_timestamp      


^ Reaper version 5.965 Ultraschall version 4.00SuppressErrorMessages

Lua: boolean retval = ultraschall.SuppressErrorMessages(boolean flag)

Allows you to suppress error-messages.
If you pass true, all error messages will be suppressed, until you run the function again passing false.

Note: You should supress error-messages only temprarily and "unsuppress" them again, after your critical stuff is finished.
Otherwise, someone using your functions will have no error-messages to debug with.

Returns false, if parameter isn't boolean. Unlike most other function, this will never create an error-message!

Returnvalues:
boolean retval
true, setting was successful; false, you didn't pass a boolean as parameter

Parameters:
boolean flag
true, suppress error-messages; false, don't suppress error-messages


^ Reaper version 5.40 Ultraschall version 4.00ToggleIDE_Errormessages

Lua: boolean retval = ultraschall.ToggleIDE_Errormessages(optional boolean togglevalue)

Toggles or sets, if the error-messaging system shall output it's errors to Reaper's IDE(true) or not(false).
When set true, it will show the errormessages at the bottom of the IDE, as you are used by Reaper's own functions.

Returnvalues:
boolean retval
true, if errors will be shown at the bottom of the IDE; false, if not

Parameters:
optional boolean togglevalue
true, if errormessages shall be shown at the bottom of the IDE, false if not. If omitted, it toggles what was set before.


^ Reaper version 5.77 Ultraschall version 4.00APIExists

Lua: boolean retval = ultraschall.APIExists(string functionname)

returns true, if a certain function/variable exists in ultraschall.

returns false if nothing has been found

Returnvalues:
boolean retval
true, if element exists; false if it doesn't exist

Parameters:
string functionname
the name of the function to check for; only the functionname without ultraschall. !


^ Reaper version 5.40 Ultraschall version 4.00ApiTest

Lua: ultraschall.ApiTest()

Displays a message to show, which parts of the Ultraschall-API are turned on and which are turned off.


^ Reaper version 6.10 Ultraschall version 4.2EditReaScript

Lua: boolean retval, optional command_id = ultraschall.EditReaScript(optional string filename, optional boolean add_ultraschall_api, optional integer add_to_actionlist_section, optional integer x_pos, optional integer y_pos, optional integer width, optional integer height)

Opens a script in Reaper's ReaScript-IDE.

If the file does not exist yet, it will try to create it. If parameter filename doesn't contain a valid directory, it will try to create the script in the Scripts-folder of Reaper.

Setting filename=nil will open the last one edited using this function.

returns false in case of an error

Returnvalues:
boolean retval
true, opening was successful; false, opening was unsuccessful
optional integer command_id
the command-id of the script, when it gets newly created

Parameters:
optional string filename
the filename of the new reascript-file to create(add .lua or .py or .eel to select the language).
nil, opens the last ReaScript-file you opened with this function
optional boolean add_ultraschall_api
true, add Ultraschall-API-call into the script(only in newly created ones!); false or nil, just open a blank script
optional integer add_to_actionlist_section
the section, into which you want to add the script
nil, don't add, only open the script in IDE
0, Main
100, Main (alt recording) Note: If you already added to main(section 0), this function automatically adds the script to Main(alt) as well.
32060, MIDI Editor
32061, MIDI Event List Editor
32062, MIDI Inline Editor
32063, Media Explorer
optional integer x_pos
x-position of the ide-window in pixels; nil, use the last one used
optional integer y_pos
y-position of the ide-window in pixels; nil, use the last one used
optional integer width
width of the ide-window in pixels; nil, use the last one used
optional integer height
height of the ide-window in pixels; nil, use the last one used


^ Reaper version 5.40 Ultraschall version 4.2RFR

Lua: ... = RFR(integer length, ...)

returns only the first x return-values, as given by length.

You can put the return-values of another function and just get the first x ones. So if the function returns 10 returnvalues,
but you only need the first two, set length=2 and add the function(with the 10 returnvalues) after it as second parameter.


For example:

integer r, integer g, integer b = reaper.ColorFromNative(integer col)

returns three colorvalues. If you only want the first one(r), use it this way:

r=RFR(1, reaper.ColorFromNative(12739))



returns nil in case of an error

Returnvalues:
various ...
the requested first-n returnvalues

Parameters:
integer length
the number of the first return-values to return
various ...
further parameters, which can be multiple values or just the return-values of another function.


^ Reaper version 5.40 Ultraschall version 4.2RLR

Lua: ... = RLR(integer length, ...)

returns only the last x return-values, as given by length.

You can put the return-values of another function and just get the last x ones. So if the function returns 10 returnvalues,
but you only need the last two, set length=2 and add the function(with the 10 returnvalues) after it as second parameter.


For example:

integer r, integer g, integer b = reaper.ColorFromNative(integer col)

returns three colorvalues. If you only want the last one(b), use it this way:

b=RLR(1, reaper.ColorFromNative(12739))



returns nil in case of an error

Returnvalues:
various ...
the requested last-n returnvalues

Parameters:
integer length
the number of the last return-values to return
various ...
further parameters, which can be multiple values or just the return-values of another function.


^ Reaper version 5.40 Ultraschall version 4.2RRR

Lua: ... = RRR(integer position, integer length, ...)

returns only the x return-values between position and position+length.

You can put the return-values of another function and just get the ones between position and position+length. So if the function returns 10 returnvalues,
but you only need the third through the fifth, set position=3 and length=3 and add the function(with the 10 returnvalues) after it as third parameter.


For example:

integer r, integer g, integer b = reaper.ColorFromNative(integer col)

returns three colorvalues. If you only want the middle one(g), use it this way:

g=RLR(2, 1, reaper.ColorFromNative(12739))



returns nil in case of an error

Returnvalues:
various ...
the requested n returnvalues between position and length+position

Parameters:
integer position
the first return-value to return
integer length
the number of return-values to return(position+length)
various ...
further parameters, which can be multiple values or just the return-values of another function.


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPanEnv

Lua: boolean retval = ultraschall.ActivateTrackPanEnv(integer track)

activates a pan-envelope of a track

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
integer track
the track, whose pan-envelope you want to activate; 1, for the first track


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPanEnv_TrackObject

Lua: boolean retval = ultraschall.ActivateTrackPanEnv_TrackObject(MediaTrack track)

activates a pan-envelope of a MediaTrack-object

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
MediaTrack track
the track, whose pan-envelope you want to activate


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPreFXPanEnv

Lua: boolean retval = ultraschall.ActivateTrackPreFXPanEnv(integer track)

activates a preFX-pan-envelope of a track

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
integer track
the track, whose preFX-pan-envelope you want to activate; 1, for the first track


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPreFXPanEnv_TrackObject

Lua: boolean retval = ultraschall.ActivateTrackPreFXPanEnv_TrackObject(MediaTrack track)

activates a preFX-pan-envelope of a MediaTrack-object

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
MediaTrack track
the track, whose prefx-pan-envelope you want to activate


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPreFXVolumeEnv

Lua: boolean retval = ultraschall.ActivateTrackPreFXVolumeEnv(integer track)

activates a preFX-volume-envelope of a track

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
integer track
the track, whose preFX-volume-envelope you want to activate; 1, for the first track


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackPreFXVolumeEnv_TrackObject

Lua: boolean retval = ultraschall.ActivateTrackPreFXVolumeEnv_TrackObject(MediaTrack track)

activates a preFX-volume-envelope of a MediaTrack-object

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
MediaTrack track
the track, whose prefx-volume-envelope you want to activate


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackTrimVolumeEnv

Lua: boolean retval = ultraschall.ActivateTrackTrimVolumeEnv(integer track)

activates a trim-volume-envelope of a track

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
integer track
the track, whose trim-volume-envelope you want to activate; 1, for the first track


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackTrimVolumeEnv_TrackObject

Lua: boolean retval = ultraschall.ActivateTrackTrimVolumeEnv_TrackObject(MediaTrack track)

activates a trim-volume-envelope of a MediaTrack-object

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
MediaTrack track
the track, whose trim-volume-envelope you want to activate


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackVolumeEnv

Lua: boolean retval = ultraschall.ActivateTrackVolumeEnv(integer track)

activates a volume-envelope of a track

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
integer track
the track, whose volume-envelope you want to activate; 1, for the first track


^ Reaper version 6.10 Ultraschall version 4.1ActivateTrackVolumeEnv_TrackObject

Lua: boolean retval = ultraschall.ActivateTrackVolumeEnv_TrackObject(MediaTrack track)

activates a volume-envelope of a MediaTrack-object

returns false in case of error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
MediaTrack track
the track, whose volume-envelope you want to activate


^ Reaper version 6.05 Ultraschall version 4.1GetAllTakeEnvelopes

Lua: integer number_of_takeenvelopes, table TakeEnvelopes_Table = ultraschall.GetAllTakeEnvelopes()

Returns all TakeEnvelopes of all MediaItems from the current project as a handy table

The format of the table is as follows:
    TakeEnvelopes[takeenvelope_idx]["MediaItem"] - the idx of the MediaItem
    TakeEnvelopes[takeenvelope_idx]["MediaItem_Take"] - the idx of the trake of the MediaItem
    TakeEnvelopes[takeenvelope_idx]["MediaItem_Take_Name"] - the name of the MediaItek_Take
    TakeEnvelopes[takeenvelope_idx]["EnvelopeObject"] - the TakeEnvelopeObject in question
    TakeEnvelopes[takeenvelope_idx]["EnvelopeName"] - the name of of TakeEnvelopeObject

Returnvalues:
integer number_of_takeenvelopes
the number of TakeEnvelopes found in the current project
table TakeEnvelopes_Table
all found TakeEnvelopes as a handy table(see description for details)


^ Reaper version 5.52 Ultraschall version 4.00GetAllTrackEnvelopes

Lua: array TrackEnvelopeArray, integer number_of_tracks, integer FirstEnvelopeTrackNumber, integer FirstEnvelopeMaster = ultraschall.GetAllTrackEnvelopes()

returns all TrackEnvelopes of the current project as a table, number of tracks, the first track that has an envelope, if the master track has an envelope(0) or not (-1)

Returnvalues:
array TrackEnvelopeArray
a table with all envelopes of the current project
the table works as follows:
TrackEnvelopeArray[Tracknumber][0] - number of envelopes for track Tracknumber
TrackEnvelopeArray[Tracknumber][1][Envelopenumber] - the envelope Envelopenumber of track Tracknumber

tracknumber of 0 is for the master track
integer number_of_tracks
the number of tracks, covered in the TrackEnvelopeArray
integer FirstEnvelopeTrackNumber
the number of the first track to have an envelope; -1 if theres none
integer FirstEnvelopeMaster
0, if the master-track has an envelope, -1 if not.


^ Reaper version 6.10 Ultraschall version 4.1GetTakeEnvelopeUnderMouseCursor

Lua: TakeEnvelope env, MediaItem_Take take, number projectposition = ultraschall.GetTakeEnvelopeUnderMouseCursor()

returns the take-envelope underneath the mouse


Returnvalues:
TakeEnvelope env
the take-envelope found unterneath the mouse; nil, if none has been found
MediaItem_Take take
the take from which the take-envelope is
number projectposition
the project-position


^ Reaper version 6.10 Ultraschall version 4.1GetTakeEnvelopeUnderMouseCursor

Lua: TakeEnvelope env, MediaItem_Take take, number projectposition = ultraschall.GetTakeEnvelopeUnderMouseCursor()

returns the take-envelope underneath the mouse


Returnvalues:
TakeEnvelope env
the take-envelope found unterneath the mouse; nil, if none has been found
MediaItem_Take take
the take from which the take-envelope is
number projectposition
the project-position


^ Reaper version 6.10 Ultraschall version 4.1IsAnyMuteEnvelopeVisible

Lua: boolean retval = ultraschall.IsAnyMuteEnvelopeVisible(string name)

returns, if any mute-envelopes are currently set to visible in the current project

Visible=true does include mute-envelopes, who are scrolled outside of the arrangeview


Returnvalues:
boolean retval
true, there are visible mute-envelopes in the project; false, no mute-envelope visible

Parameters:
string name
the name of the envelope; case-sensitive, just take the one displayed in the envelope-lane
Standard-Envelopes are:
     "Volume (Pre-FX)", "Pan (Pre-FX)", "Width (Pre-FX)", "Volume", "Pan", "Width", "Trim Volume", "Mute"
Plugin's envelopes can also be checked against, like
     "Freq-Band 1 / ReaEQ"


^ Reaper version 6.10 Ultraschall version 4.1IsEnvelope_Track

Lua: boolean retval = ultraschall.IsEnvelope_Track(TrackEnvelope env)

returns, if the envelope is a track envelope(true) or a take-envelope(false)

returns nil in case of an error


Returnvalues:
boolean retval
true, the envelope is a TrackEnvelope; false, the envelope is a TakeEnvelope

Parameters:
TrackEnvelope env
the envelope to check


^ Reaper version 6.10 Ultraschall version 4.1IsTrackEnvelopeVisible_ArrangeView

Lua: boolean retval = ultraschall.IsTrackEnvelopeVisible_ArrangeView(TrackEnvelope env)

returns, if the envelope is currently visible within arrange-view

returns nil in case of an error


Returnvalues:
boolean retval
true, the envelope is a TrackEnvelope; false, the envelope is a TakeEnvelope

Parameters:
TrackEnvelope env
the envelope to check for visibility


^ Reaper version 6.02 Ultraschall version 4.00GetArmState_Envelope

Lua: integer retval = ultraschall.GetArmState_Envelope(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current armed-state of a TrackEnvelope-object.

It is the entry ARM

returns nil in case of error

Returnvalues:
integer retval
0, unarmed; 1, armed

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose armed-state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_Act

Lua: integer act, integer automation_settings = ultraschall.GetEnvelopeState_Act(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current act-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry ACT

returns nil in case of error

Returnvalues:
integer act
0, bypass on
1, no bypass
integer automation_settings
automation item-options for this envelope
-1, project default behavior, outside of automation items
0, automation items do not attach underlying envelope
1, automation items attach to the underlying envelope on the right side
2, automation items attach to the underlying envelope on both sides
3, no automation item-options for this envelope
4, bypass underlying envelope outside of automation items

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_DefShape

Lua: integer shape, integer pitch_custom_envelope_range_takes, integer pitch_snap_values = ultraschall.GetEnvelopeState_DefShape(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current default-shape-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry DEFSHAPE

returns nil in case of error

Returnvalues:
integer shape
0, linear
1, square
2, slow start/end
3, fast start
4, fast end
5, bezier
integer pitch_custom_envelope_range_takes
the custom envelope range as set in the Pitch Envelope Settings; only available in take-fx-envelope "Pitch"
-1, if unset or for non pitch-envelopes
0, Custom envelope range-checkbox unchecked
1-2147483647, the actual semitones
integer pitch_snap_values
the snap values-dropdownlist as set in the Pitch Envelope Settings-dialog; only available in take-fx-envelope "Pitch"
-1, unset/Follow global default
0, Off
1, 1 Semitone
2, 50 cent
3, 25 cent
4, 10 cent
5, 5 cent
6, 1 cent

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_EnvName

Lua: string envelopename, optional integer fx_env_id, optional string wet_byp, optional number minimum_range, optional number maximum_range, optional number unknown = ultraschall.GetEnvelopeState_EnvName(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current envelope-name-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the opening <-tag of the EnvelopeStateChunk

returns nil in case of error

Returnvalues:
string envelopename
the name of the envelope, usually:
  VOLENV2 - for Volume-envelope
  PANENV2 - for Pan-envelope
  WIDTHENV2 - for Width-envelope
  VOLEN - for Pre-FX-Volume-envelope
  PANENV - for Pre-FX-Pan-envelope
  WIDTHENV - for Pre-FX-Width-envelope
  MUTEENV - for Mute-envelope
  VOLENV3 - for Trim-Volume-envelope
  PARMENV - an envelope for an FX-plugin
optional integer fx_env_id
fx_env is the id of the envelope, as provided by this fx; beginning with 1 for the first
optional string wet_byp
wet_byp is either "" if not existing, wet or bypass
optional number minimum_range
the minimum value, accepted by this envelope; 6 digits-precision
optional number maximum_range
the maximum-value, accepted by this envelope; 6 digits-precision
optional number unknown
unknown

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_LaneHeight

Lua: integer height, integer compacted = ultraschall.GetEnvelopeState_LaneHeight(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current laneheight-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry LANEHEIGHT

returns nil in case of error

Returnvalues:
integer height
the height of this envelope in pixels; 24 - 263 pixels
integer compacted
1, envelope-lane is compacted("normal" height is not shown but still stored in height);
0, envelope-lane is "normal" height

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_NumbersOnly

Lua: table values = ultraschall.GetEnvelopeState_NumbersOnly(string state, optional string EnvelopeStateChunk, optional string functionname, optional boolean numbertoggle)

returns a state from an EnvelopeStateChunk.

It only supports single-entry-states with numbers/integers, separated by spaces!
All other values will be set to nil and strings with spaces will produce weird results!

returns nil in case of an error

Returnvalues:
table values
all values found as numerical indexed array

Parameters:
string state
the state, whose attributes you want to retrieve
string TrackStateChunk
a statechunk of an envelope
optional string functionname
if this function is used within specific gettrackstate-functions, pass here the "host"-functionname, so error-messages will reflect that
optional boolean numbertoggle
true or nil; converts all values to numbers; false, keep them as string versions


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_PT

Lua: number position, integer volume, integer point_shape_1, integer point_shape_2, integer selected, number bezier_tens1, number bezier_tens2 = ultraschall.GetEnvelopeState_PT(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current state of a certain envelope-point within a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry PT

returns nil in case of error

Returnvalues:
number position
position of the point in seconds
integer volume
volume as fader-value
integer point_shape
may disappear with certain shapes, when point is unselected
the values for point_shape_1 and point_shape_2 are:
0 0, linear
1 0, square
2 0, slow start/end
3 0, fast start
4 0, fast end
5 1, bezier
integer selected
1, selected; disappearing, unselected
number unknown
disappears, if no bezier is set
number bezier_tens2
disappears, if no bezier is set; -1 to 1
0, for no bezier tension
-0.5, for fast-start-beziertension
0.5, for fast-end-beziertension
1, for square-tension

Parameters:
integer index
the index-number of the envelope-point, whose states you want to have
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_PooledEnvInstance

Lua: integer id, number position, number length, number start_offset, number playrate, integer selected, number baseline, integer loopsource, integer i, number j, integer pool_id, integer mute = ultraschall.GetEnvelopeState_PooledEnvInstance(integer index, TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current state of a certain automation-item within a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry POOLEDENVINST

returns nil in case of error

Returnvalues:
integer id
counter of automation-items; 1-based
number position
position in seconds
number length
length in seconds
number start_offset
offset in seconds
number playrate
playrate; minimum value is 0.001; default is 1.000
integer selected
1, automation item is selected; 0, automation item isn't selected
number baseline
0(-100) to 1(+100); default 0.5(0)
number amplitude
-2(-200) to 2(+200); default 1 (100)
integer loopsource
Loop Source; 0 and 1 are allowed settings; 1 is default
integer i
unknown; 0 is default
number j
unknown; 0 is default
integer pool_id
counts the automation-item-instances in this project, including deleted ones; 1-based
integer mute
1, mute automation-item; 0, unmute automation-item

Parameters:
integer index
the index-number of the automation-item, whose states you want to have
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_Vis

Lua: integer visible, integer lane, integer unknown = ultraschall.GetEnvelopeState_Vis(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current visibility-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry VIS

returns nil in case of error

Returnvalues:
integer visible
1, envelope is visible
0, envelope is not visible
integer lane
1, envelope is in it's own lane
0, envelope is in media-lane
integer unknown
unknown; default=1

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 6.02 Ultraschall version 4.00GetEnvelopeState_Voltype

Lua: integer voltype = ultraschall.GetEnvelopeState_Voltype(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Returns the current voltype-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry VOLTYPE

returns nil in case of error

Returnvalues:
integer voltype
1, default volume-type is fader-scaling; if VOLTYPE-entry is not existing, default volume-type is amplitude-scaling

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose state you want to know; nil, to use parameter EnvelopeStateChunk instead
optional string EnvelopeStateChunk
if TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameter, to get that armed state


^ Reaper version 5.52 Ultraschall version 4.00GetAllTrackEnvelopes

Lua: array TrackEnvelopeArray, integer number_of_tracks, integer FirstEnvelopeTrackNumber, integer FirstEnvelopeMaster = ultraschall.GetAllTrackEnvelopes()

returns all TrackEnvelopes of the current project as a table, number of tracks, the first track that has an envelope, if the master track has an envelope(0) or not (-1)

Returnvalues:
array TrackEnvelopeArray
a table with all envelopes of the current project
the table works as follows:
TrackEnvelopeArray[Tracknumber][0] - number of envelopes for track Tracknumber
TrackEnvelopeArray[Tracknumber][1][Envelopenumber] - the envelope Envelopenumber of track Tracknumber

tracknumber of 0 is for the master track
integer number_of_tracks
the number of tracks, covered in the TrackEnvelopeArray
integer FirstEnvelopeTrackNumber
the number of the first track to have an envelope; -1 if theres none
integer FirstEnvelopeMaster
0, if the master-track has an envelope, -1 if not.


^ Reaper version 5.40 Ultraschall version 4.00GetClosestEnvelopePointIDX_ByTime

Lua: integer idxpre, array EnvelopePointObjectPre, integer idxpost, array EnvelopePointObjectPost = ultraschall.GetClosestEnvelopePointIDX_ByTime(integer Tracknumber, string EnvelopeName, number CheckTime)

Returns the idxs and EnvelopePointObject of the envelope-points closest to timeposition CheckTime
returns -1 in case of error

Returnvalues:
integer idxpre
the idx of the closest envelopepoint at or before CheckTime
array EnvelopePointObjectPre
an EnvelopePointObject of idxpre
integer idxpost
the idx of the closest envelopepoint after CheckTime
array EnvelopePointObjectPost
an EnvelopePointObject of idxpost

Parameters:
integer Tracknumber
the number of the track, beginning with 1. Use 0 for Master Track.
string EnvelopeName
the name of the envelope-lane
number CheckTime
the time in seconds to check for the closest envelope-points


^ Reaper version 5.40 Ultraschall version 4.00GetEnvelopePoint

Lua: number time, number value, integer shape, number tension, boolean selected, number dBVal, array EnvelopePointObject = ultraschall.GetEnvelopePoint(integer Tracknumber, string EnvelopeName, integer idx)

Returns the values for the idxth envelope point in Tracknumber->EnvelopeName.

returns -1 in case of error

Returnvalues:
number time
the time of the envelope point
number value
the raw-value of the envelope point
integer shape
the shape of this envelope
0 - Linear
1 - Square
2 - Slow start/end
3 - Fast start
4 - Fast end
5 - Bezier
number tension
the intensity of the tension of the shape
boolean selected
true, if this point is selected; false if not
number dBVal
the envelopevalue converted to dB
array EnvelopePointObject
an array with all elements of an envelopepoint
[1] - TrackEnvelope-object
[2] - Envelope-idx, beginning with 0 for the first one
[3] - time
[4] - value
[5] - shape
[6] - tension
[7] - selected
[8] - dBValue converted from value

Parameters:
integer Tracknumber
the number of the track, beginning with 1. Use 0 for Master Track.
string EnvelopeName
the name of the envelope-lane
integer idx
the number of the envelope-point, beginning with 0


^ Reaper version 5.40 Ultraschall version 4.00GetEnvelopePointIDX_Between

Lua: string EnvelopeString, array EnvelopePointArray = ultraschall.GetEnvelopePointIDX_Between(integer Tracknumber, string EnvelopeName, number startposition, number endposition)

Returns a string and an EnvelopePointArray with all idx/EnvelopePointObjects of all envelopepoints between startposition and endposition in the EnvelopeName-lane.
returns -1 in case of error

Returnvalues:
string EnvelopeString
a string with all envelope-point-idx in the selection, separated by commas.
array EnvelopePointArray
an array with all EnvelopePointObjects of all envelope-points in selection.

Parameters:
integer Tracknumber
the number of the track. 1 for track 1, 2 for track 2, etc. 0 for Master-track.
string EnvelopeName
the name of the envelope-lane, where you want to have the envelope-points of.
number startposition
the startposition of the selection in seconds. Must be bigger than or equal 0.
number endposition
the endposition of the selection in seconds. Must be bigger than startposition.


^ Reaper version 5.975 Ultraschall version 4.00GetLastEnvelopePoint_TrackEnvelope

Lua: boolean retval, optional integer envpointidx, optional number time, optional number value, optional integer shape, optional number tension, optional boolean selected = ultraschall.GetLastEnvelopePoint_TrackEnvelope(TrackEnvelope Envelope)

Gets the values of the last envelope-point in TrackEnvelope/MediaItemEnvelope.

Note: there's a "hidden" last envelopepoint in every Envelope, which will be ignored by this function. It will return the last visible envelope-point instead!

Returns false in case of an error


Returnvalues:
boolean retval
true, getting the envelopepoint was successful; false, in case of an error
optional integer envpointidx
the idx of the found envelope-point; with 0 for the first one on the Envelope
optional number time
the time of the envelope-point in seconds
optional number value
the value of the envelope-point
optional integer shape
the shape of the envelope-point
0 - Linear
1 - Square
2 - Slow start/end
3 - Fast start
4 - Fast end
5 - Bezier
optional number tension
the intensity of the tension of the shape
optional boolean selected
true, envelope-point is selected; false, it is not selected

Parameters:
TrackEnvelope Envelope
the Trackenvelope/MediaItemenvelope, whose last point you want


^ Reaper version 5.981 Ultraschall version 4.1ActivateEnvelope

Lua: boolean retval = ultraschall.ActivateEnvelope(TrackEnvelope env, optional boolean visible, optional boolean bypass)

Activates an envelope, so it can be displayed in the arrange-view.

Will add an envelope-point at position 0 in the envelope, if no point is in the envelope yet

returns false in case of an error


Returnvalues:
boolean retval
true, activating was successful; false, activating was unsuccessful

Parameters:
TrackEnvelope Envelope
the envelope, which you want to activate
optional boolean visible
true or nil, show envelope; false, don't show envelope
optional boolean bypass
true or nil, don't bypass envelope; false, bypass envelope


^ Reaper version 5.40 Ultraschall version 4.00CheckEnvelopePointObject

Lua: boolean retval = ultraschall.CheckEnvelopePointObject(array EnvelopePointObject)

Checks, if EnvelopePointObject is valid or not.

returns false in case of an error

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointObject
an array with all information of an envelope point


^ Reaper version 5.40 Ultraschall version 4.00CountEnvelopePoints

Lua: integer envpoint_count = ultraschall.CountEnvelopePoints(integer Tracknumber, string EnvelopeName)

Counts and returns the number of envelope-points in track Tracknumber, envelopelane EnvelopeName.

returns -1 in case of error

Returnvalues:
integer envpoint_count
the number of envelope-points in requested track+envelope-lane

Parameters:
integer Tracknumber
the number of the track, beginning with 1. Use 0 for Master Track.
string EnvelopeName
the name of the envelope-lane


^ Reaper version 5.40 Ultraschall version 4.00CreateEnvelopePointObject

Lua: boolean retval, array EnvelopePointObject = ultraschall.CreateEnvelopePointObject(TrackEnvelope TrackEnvelope, integer idx, number time, number value, integer shape, number tension, boolean selected)

Creates a new EnvelopePointObject, that can be used by other ultraschall-api-envelope-functions

returns false in case of error

Returnvalues:
boolean retval
false in case of error, true in case of success.
array EnvelopePointObject
an array with all elements of the envelopepoint
[1] - TrackEnvelope-object
[2] - Envelope-idx, beginning with 0 for the first one
[3] - time
[4] - value
[5] - shape
[6] - tension
[7] - selected
[8] - dBValue converted from value

Parameters:
TrackEnvelope env
the track-envelope, in which this EnvelopePointObject shall be
integer idx
the number of the envelope-point, beginning with 0
number time
the time of the envelope point in seconds
number value
the raw-value of the envelope point
integer shape
the shape of this envelope
0 - Linear
1 - Square
2 - Slow start/end
3 - Fast start
4 - Fast end
5 - Bezier
number tension
the intensity of the tension of the shape
boolean selected
true, if this point is selected; false if not


^ Reaper version 6.10 SWS version 2.10.0.1 Ultraschall version 4.2GetTrackEnvelope_ClickState

Lua: boolean clickstate, number position, MediaTrack track, TrackEnvelope envelope, integer EnvelopePointIDX = ultraschall.GetTrackEnvelope_ClickState(integer mouse_button)

Returns the currently clicked Envelopepoint and TrackEnvelope, as well as the current timeposition.

Works only, if the mouse is above the EnvelopePoint while having it clicked!

Returns false, if no envelope is clicked at


Returnvalues:
boolean clickstate
true, an envelopepoint has been clicked; false, no envelopepoint has been clicked
number position
the position, at which the mouse has clicked
MediaTrack track
the track, from which the envelope and it's corresponding point is taken from
TrackEnvelope envelope
the TrackEnvelope, in which the clicked envelope-point lies
integer EnvelopePointIDX
the id of the clicked EnvelopePoint

Parameters:
integer mouse_button
the mousebutton, that shall be clicked at the envelope; you can combine them as flags
-1, get all states
&1, only left mouse button
&2, only right mouse button
&4, Ctrl/Cmd-key
&8, Shift-key
&16, Alt key
&32, Windows key
&64, Middle mouse button


^ Reaper version 6.10 SWS version 2.10.0.1 Ultraschall version 4.2GetTrackEnvelope_ClickState

Lua: boolean clickstate, number position, MediaTrack track, TrackEnvelope envelope, integer EnvelopePointIDX = ultraschall.GetTrackEnvelope_ClickState(integer mouse_button)

Returns the currently clicked Envelopepoint and TrackEnvelope, as well as the current timeposition.

Works only, if the mouse is above the EnvelopePoint while having it clicked!

Returns false, if no envelope is clicked at


Returnvalues:
boolean clickstate
true, an envelopepoint has been clicked; false, no envelopepoint has been clicked
number position
the position, at which the mouse has clicked
MediaTrack track
the track, from which the envelope and it's corresponding point is taken from
TrackEnvelope envelope
the TrackEnvelope, in which the clicked envelope-point lies
integer EnvelopePointIDX
the id of the clicked EnvelopePoint

Parameters:
integer mouse_button
the mousebutton, that shall be clicked at the envelope; you can combine them as flags
-1, get all states
&1, only left mouse button
&2, only right mouse button
&4, Ctrl/Cmd-key
&8, Shift-key
&16, Alt key
&32, Windows key
&64, Middle mouse button


^ Reaper version 5.40 Ultraschall version 4.00IsValidEnvStateChunk

Lua: boolean valid = ultraschall.IsValidEnvStateChunk(string EnvelopeStateChunk)

returns, if a EnvelopeStateChunk is a valid statechunk

returns false, in case of an error

Returnvalues:
boolean valid
true, if the string is a valid statechunk; false, if not a valid statechunk

Parameters:
string EnvelopeStateChunk
a string to check, if it's a valid EnvelopeStateChunk


^ Reaper version 5.941 Ultraschall version 4.00IsValidEnvelopePointArray

Lua: boolean retval = ultraschall.IsValidEnvelopePointArray(EnvelopePointArray EnvelopePointArray)

Checks, if an EnvelopePointArray is a valid one.

Returns false in case of an error

Returnvalues:
boolean retval
true, EnvelopePointArray is a valid one; false, EnvelopePointArray isn't valid

Parameters:
EnvelopePointArray EnvelopePointArray
the EnvelopePointArray to check for it's validity


^ Reaper version 5.40 Ultraschall version 4.00IsValidEnvelopePointObject

Lua: boolean retval = ultraschall.IsValidEnvelopePointObject(array EnvelopePointObject)

Checks, if EnvelopePointObject is valid or not.

returns false in case of an error

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointObject
an array with all information of an envelope point


^ Reaper version 5.95 Ultraschall version 4.00SetArmState_Envelope

Lua: boolean retval, optional string EnvelopeStateChunk = ultraschall.SetArmState_Envelope(TrackEnvelope TrackEnvelope, integer state, optional string EnvelopeStateChunk)

Sets the new armed-state of a TrackEnvelope-object.

returns false in case of error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful
optional string EnvelopeStateChunk
the altered EnvelopeStateChunk, when parameter TrackEnvelope is set to nil

Parameters:
TrackEnvelope TrackEnvelope
the TrackEnvelope, whose armed-state you want to change
integer state
0, unarmed; 1, armed
optional string EnvelopeStateChunk
if parameter TrackEnvelope is set to nil, you can pass an EnvelopeStateChunk into this parameters and change its arm-state


^ Reaper version 6.10 Ultraschall version 4.1SetEnvelopeState_Act

Lua: boolean retval = ultraschall.SetEnvelopeState_Act(TrackEnvelope env, integer act, integer automation_settings, optional string EnvelopeStateChunk)

sets the current bypass and automation-items-settings-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry ACT

returns false in case of error


Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful
string EnvelopeStateChunk
the altered EnvelopeStateChunk

Parameters:
TrackEnvelope env
the envelope, in whose envelope you want set the bypass and automation-item-states; nil, to use parameter EnvelopeStateChunk instead
integer act
bypass-setting;
  0, bypass on
  1, no bypass
integer automation_settings
automation item-options for this envelope
-1, project default behavior, outside of automation items
0, automation items do not attach underlying envelope
1, automation items attach to the underlying envelope on the right side
2, automation items attach to the underlying envelope on both sides
3, no automation item-options for this envelope
4, bypass underlying envelope outside of automation items
optional string EnvelopeStateChunk
an EnvelopeStateChunk, in which you want to set these settings


^ Reaper version 6.10 Ultraschall version 4.1SetEnvelopeState_DefShape

Lua: boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_DefShape(TrackEnvelope env, integer shape, integer pitch_custom_envelope_range, integer pitch_snap_values, optional string EnvelopeStateChunk)

sets the current default-shape-states and pitch-snap-settings of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry DEFSHAPE

returns false in case of error


Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful
string EnvelopeStateChunk
the altered EnvelopeStateChunk

Parameters:
TrackEnvelope env
the envelope, in whose envelope you want set the default shape and pitch-snap states; nil, to use parameter EnvelopeStateChunk instead
integer shape
the default shape of envelope-points
0, linear
1, square
2, slow start/end
3, fast start
4, fast end
5, bezier
integer pitch_custom_envelope_range_takes
the custom envelope range as set in the Pitch Envelope Settings; only available in take-fx-envelope "Pitch"
-1, if unset or for non pitch-envelopes
0, Custom envelope range-checkbox unchecked
1-2147483647, the actual semitones
integer pitch_snap_values
the snap values-dropdownlist as set in the Pitch Envelope Settings-dialog; only available in take-fx-envelope "Pitch"
-1, unset/Follow global default
0, Off
1, 1 Semitone
2, 50 cent
3, 25 cent
4, 10 cent
5, 5 cent
6, 1 cent
optional string EnvelopeStateChunk
an EnvelopeStateChunk, in which you want to set these settings


^ Reaper version 6.10 Ultraschall version 4.1SetEnvelopeState_LaneHeight

Lua: boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_LaneHeight(TrackEnvelope env, integer height, integer compacted, optional string EnvelopeStateChunk)

sets the current height-states and compacted-settings of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry LANEHEIGHT

returns false in case of error


Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful
string EnvelopeStateChunk
the altered EnvelopeStateChunk

Parameters:
TrackEnvelope env
the envelope, whose envelope you want set the height and compacted-states; nil, to us parameter EnvelopeStateChunk instead
integer height
the height of the laneheight; the height of this envelope in pixels; 24 - 263 pixels
integer compacted
1, envelope-lane is compacted("normal" height is not shown but still stored in height);
0, envelope-lane is "normal" height
optional string EnvelopeStateChunk
an EnvelopeStateChunk, in which you want to set these settings


^ Reaper version 6.10 Ultraschall version 4.1SetEnvelopeState_Vis

Lua: boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_Vis(TrackEnvelope env, integer visibility, integer lane, integer unknown, optional string EnvelopeStateChunk)

sets the current visibility-state of a TrackEnvelope-object or EnvelopeStateChunk.

It is the state entry VIS

returns false in case of error


Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful
string EnvelopeStateChunk
the altered EnvelopeStateChunk

Parameters:
TrackEnvelope env
the envelope, in whose envelope you want set the visibility states; nil, to us parameter EnvelopeStateChunk instead
integer visibility
the visibility of the envelope; 0, invisible; 1, visible
integer lane
the position of the envelope in the lane; 0, envelope is in media-lane; 1, envelope is in it's own lane
integer unknown
unknown; default=1
optional string EnvelopeStateChunk
an EnvelopeStateChunk, in which you want to set these settings


^ Reaper version 5.40 Ultraschall version 4.00AddEnvelopePoints_EnvelopePointArray

Lua: boolean retval = ultraschall.AddEnvelopePoints_EnvelopePointArray(array EnvelopePointArray, boolean sort_in)

Adds the envelope-points, as defined in the EnvelopePointObjects, in the EnvelopePointArray.
returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointArray
an array with all EnvelopePointObjects you want to insert
boolean sort_in
set true, if setting multiple points at once and call Envelope_SortPoints when done.


^ Reaper version 5.40 Ultraschall version 4.00AddEnvelopePoints_EnvelopePointObject

Lua: boolean retval = ultraschall.AddEnvelopePoints_EnvelopePointObject(array EnvelopePointObject, boolean sort_in)

Adds an envelope-point, as defined in EnvelopePointObject.
returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointObject
an array with all information of an envelope point
boolean sort_in
set true, if setting multiple points at once and call Envelope_SortPoints when done.


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00DeleteEnvelopePoints_EnvelopePointArray

Lua: boolean retval = ultraschall.DeleteEnvelopePoints_EnvelopePointArray(array EnvelopePointArray)

Deletes the envelope-points, as defined in the EnvelopePointObjects, in the EnvelopePointArray.
returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointArray
an array with all EnvelopePointObjects you want to insert


^ Reaper version 5.40 SWS version 2.8.8 Ultraschall version 4.00DeleteEnvelopePoints_EnvelopePointObject

Lua: boolean retval = ultraschall.DeleteEnvelopePoints_EnvelopePointObject(array EnvelopePointObject)

Deletes an envelope-point, as defined in EnvelopePointObject.

returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointObject
an array with all information of an envelope point


^ Reaper version 5.40 Ultraschall version 4.00MoveTrackEnvelopePointsBy

Lua: integer retval = ultraschall.MoveTrackEnvelopePointsBy(number startposition, number endposition, number moveby, MediaTrack MediaTrack, boolean cut_at_border)

Moves the envelopepoints between startposition and endposition by moveby in MediaTrack.
It moves all trackenvelope-points for all track-envelopes available.

Does NOT move item-envelopepoints!

Returns -1 in case of failure.

Returnvalues:
integer retval
-1 in case of failure

Parameters:
number startposition
the startposition in seconds
number endposition
the endposition in seconds
number moveby
in seconds, negative values: move toward beginning of project, positive values: move toward the end of project
MediaTrack MediaTrack
the MediaTrack object of the track, where the EnvelopsPoints shall be moved
boolean cut_at_border
true, cut envelope-points, that would move outside section between startposition and endposition


^ Reaper version 5.52 Ultraschall version 4.00SetEnvelopeHeight

Lua: boolean retval, string TrackEnvelopeStateChunk = ultraschall.SetEnvelopeHeight(integer Height, boolean Compacted, TrackEnvelope TrackEnvelope, string TrackEnvelopeStateChunk)

Changes the Envelope-lane-height and compactible state of TrackEnvelope or TrackEnvelopeStateChunk.

returns false in case of an error

Returnvalues:
boolean retval
true in case of success; false in case of error
string TrackEnvelopeStateChunk
the altered TrackEnvelopeStateChunk

Parameters:
integer Height
the height of the envelopelane in pixels when not compacted. Reaper accepts 24-443 currently. Nil keeps old value.
boolean Compacted
shall the envelopelane be compacted(true) or not(false). Nil keeps old value.
TrackEnvelope TrackEnvelope
the TrackEnvelope to alter, or nil to use the TrackEnvelopeStateChunk instead
optional string TrackEnvelopeStateChunk
the TrackEnvelopeStateChunk you want to alter. Will be used only, if TrackEnvelope is set to nil


^ Reaper version 5.40 Ultraschall version 4.00SetEnvelopePoints_EnvelopePointArray

Lua: boolean retval = ultraschall.SetEnvelopePoints_EnvelopePointArray(array EnvelopePointArray, boolean sort_in)

Sets envelope-points, as defined in the EnvelopePointObjects, in the EnvelopePointArray.

returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointArray
an array with all EnvelopePointObjects you want to insert
boolean sort_in
set true, if setting multiple points at once and call Envelope_SortPoints when done.


^ Reaper version 5.40 Ultraschall version 4.00SetEnvelopePoints_EnvelopePointObject

Lua: boolean retval = ultraschall.SetEnvelopePoints_EnvelopePointObject(array EnvelopePointObject, boolean sort_in)

Sets an envelope-point, as defined in EnvelopePointObject.

returns true in case of success, false in case of failure.

Returnvalues:
boolean retval
true, if it's a valid EnvelopePointObject; false if not

Parameters:
array EnvelopePointObject
an array with all information of an envelope point
boolean sort_in
set true, if setting multiple points at once and call Envelope_SortPoints when done.


^ Reaper version 5.982 Ultraschall version 4.00EventManager_AddEvent

Lua: string event_identifier = ultraschall.EventManager_AddEvent(string EventName, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, table Actions)

Adds a new event to the Ultraschall Event Manager-checking-queue.

returns nil in case of an error


Returnvalues:
string event_identifier
the unique identifier for this registered event, which can be used later for setting, deleting, etc

Parameters:
string EventName
a name for the event, which you can choose freely; duplicated eventnames are allowed
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
boolean EventPaused
false, register the event and check for it immediately; true, register the event but don't check for it yet
function CheckFunction
the function, which shall check if the event occurred
this function must return true if the event occurred and false, if not
No global variables allowed! Instead, the eventmanager will pass to it as first parameter a table which can be used for storing information
table Actions
a table which holds all actions and their accompanying sections, who shall be run when the event occurred
each entry of the table must be of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

You can have as many actions as you like, but be aware, that running too many actions may delay further eventchecking!


^ Reaper version 5.982 Ultraschall version 4.00EventManager_AddStartupEvent

Lua: string event_identifier = ultraschall.EventManager_AddStartupEvent(string EventName, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, table Actions)

Adds a new event, that shall be automatically registered at startup of the Ultraschall Event Manager.

That means, if you start the EventManager, it will be added automatically to the EventManager-checking-queue, without the need of registering it by hand.

returns nil in case of an error


Returnvalues:
string event_identifier
the unique identifier for this registered event, which can be used later for setting, deleting, etc

Parameters:
string EventName
a name for the event, which you can choose freely; duplicated eventnames are allowed
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
boolean EventPaused
false, register the event and check for it immediately; true, register the event but don't check for it yet
function CheckFunction
the function, which shall check if the event occurred
this function must return true if the event occurred and false, if not
No global variables allowed! Instead, the eventmanager will pass to the function as first parameter a table which can be used for storing information
table Actions
a table which holds all actions and their accompanying sections, who shall be run when the event occurred
each entry of the table must be of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

You can have as many actions as you like, but be aware, that running too many actions may delay further eventchecking!


^ Reaper version 5.982 Ultraschall version 4.00EventManager_CountRegisteredEvents

Lua: integer count_of_registered_events = ultraschall.EventManager_CountRegisteredEvents()

Returns the number of currently registered events in the EventManager-checking-queue


Returnvalues:
integer count_of_registered_events
the number of currently registered events


^ Reaper version 5.982 Ultraschall version 4.00EventManager_CountStartupEvents

Lua: integer count_startup_events = ultraschall.EventManager_CountStartupEvents()

Counts the currently available startup-events


Returnvalues:
integer count_startup_events
the number of currently available start-up-events for the EventManager


^ Reaper version 5.982 Ultraschall version 4.00EventManager_DebugMode

Lua: ultraschall.EventManager_DebugMode(boolean toggle)

Starts Debugmode of the EventManager, which returns additional internal states.

Allows you to get the contents of the UserSpace of a certain checkfunction of a registered event, see EventManagerDebugModeUserSpace.

Note: Debugmode is not for productive usecases, as it costs resources. Please turn it off again, after you've finished debugging.


Parameters:
boolean toggle
true, turn debugmode on; false, turn debugmode off


^ Reaper version 5.982 Ultraschall version 4.00EventManager_DebugMode_UserSpace

Lua: integer userspace_count, table userspace = ultraschall.EventManager_DebugMode_UserSpace(integer index)

Returns the current contents of the UserSpace, as stored by the checkfunction of a registered event in the EventManager.

The table is of the format:

    userspace[index]["index"]    - the name of the index
    userspace[index]["datatype"] - the datatype of the value in this userspace-index
    userspace[index]["value"]    - the value in this userspace-index

Note: Debugmode is not for productive usecases, as it costs resources. Please turn it off again, after you've finished debugging. See EventManager_DebugMode for more details on stopping DebugMode.

returns nil in case of an error


Returnvalues:
integer userspace_count
the number of values within the userspace
table userspace
the contents of the userspace as a handy table

Parameters:
integer index
the index of the event, whose UserSpace you want to retrieve


^ Reaper version 5.982 Ultraschall version 4.00EventManager_EnumerateEvents

Lua: string EventIdentifier, string EventName, string CallerScriptIdentifier, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, integer NumberOfActions, table Actions = ultraschall.EventManager_EnumerateEvents(integer id)

Gets the attributes of an already added event in the Ultraschall Event Manager-checking-queue.

returns nil in case of an error


Returnvalues:
string EventIdentifier
the EventIdentifier of the registered event
string EventName
the name of the event
string CallerScriptIdentifier
the ScriptIdentifier of the script, who registered the event
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once
   false, run until the CheckFunction returns false again
boolean EventPaused
true, eventcheck is currently paused; false, eventcheck is currently running
function CheckFunction
the function, which shall check if the event occurred
integer NumberOfActions
the number of actions currently registered with this event
table Actions
a table which holds all actions and their accompanying sections, who are run when the event occurred
each entry of the table is of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

Parameters:
integer id
the id of the currently registered event, of which you want to have the attributes; starting with 1 for the first


^ Reaper version 5.982 Ultraschall version 4.00EventManager_EnumerateEvents2

Lua: string EventIdentifier, string EventName, string CallerScriptIdentifier, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, integer NumberOfActions, table Actions = ultraschall.EventManager_EnumerateEvents2(string EventIdentifier)

Gets the attributes of an already added event in the Ultraschall Event Manager-checking-queue.

returns nil in case of an error


Returnvalues:
string EventIdentifier
the EventIdentifier of the registered event
string EventName
the name of the event
string CallerScriptIdentifier
the ScriptIdentifier of the script, who registered the event
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once
   false, run until the CheckFunction returns false again
boolean EventPaused
true, eventcheck is currently paused; false, eventcheck is currently running
function CheckFunction
the function, which shall check if the event occurred
integer NumberOfActions
the number of actions currently registered with this event
table Actions
a table which holds all actions and their accompanying sections, who are run when the event occurred
each entry of the table is of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

Parameters:
string Eventidentifier
the EventIdentifier of the currently registered event, of which you want to have the attributes


^ Reaper version 5.982 Ultraschall version 4.00EventManager_EnumerateStartupEvents

Lua: string EventIdentifier, string Eventname, string CallerScriptIdentifier, number CheckAllXSeconds, number CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean Paused, function CheckFunction, number NumberOfActions, table Actions = ultraschall.EventManager_EnumerateStartupEvents(integer index)

Enumerates already existing startupevents, that shall be automatically run at startup of the Ultraschall Event Manager.

That means, if you start the EventManager, it will be started automatically to the EventManager-checking-queue, without the need of registering it by hand.

returns nil in case of an error


Returnvalues:
string EventIdentifier
the EventIdentifier of the startup-event
string EventName
a name for the startupevent
string CallerScriptIdentifier
the ScriptIdentifier of the script, which added this event to the StartUpEvents
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
boolean Paused
true, the event shall be started as paused; false, the event shall be run immediately
function CheckFunction
the function, which shall check if the event occurred
integer NumberOfActions
the number of actions currently registered with this event
table Actions
a table which holds all actions and their accompanying sections, who are run when the event occurred
each entry of the table is of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

Parameters:
integer index
the index of the StartUp-event, whose attributes you want to get; 1 for the first, etc


^ Reaper version 5.982 Ultraschall version 4.00EventManager_EnumerateStartupEvents2

Lua: integer index, string EventIdentifier, string Eventname, string CallerScriptIdentifier, number CheckAllXSeconds, number CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean Paused, function CheckFunction, number NumberOfActions, table Actions = ultraschall.EventManager_EnumerateStartupEvents2(string EventIdentifier)

Enumerates already existing startupevents by an EventIdentifier.

StartupEvents are events, that shall be automatically run at startup of the Ultraschall Event Manager. That means, if you start the EventManager, it will be started automatically to the EventManager-checking-queue, without the need of registering it by hand.

returns nil in case of an error


Returnvalues:
integer index
the index of the StartupEvent within all StartUpEvents
string EventIdentifier
the EventIdentifier of the startup-event
string EventName
a name for the startupevent
string CallerScriptIdentifier
the ScriptIdentifier of the script, which added this event to the StartUpEvents
integer CheckAllXSeconds
only check all x seconds; 0, for constant checking
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
boolean Paused
true, the event shall be started as paused; false, the event shall be run immediately
function CheckFunction
the function, which shall check if the event occurred
integer NumberOfActions
the number of actions currently registered with this event
table Actions
a table which holds all actions and their accompanying sections, who are run when the event occurred
each entry of the table is of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

Parameters:
string EventIdentifier
the identifier of the StartupEvent, that you want to enumerate


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetEventIdentifier

Lua: string event_identifier = ultraschall.EventManager_GetEventIdentifier(integer id)

returns the EventIdentifier of a registered event, by id event is requested by number-id, with 1 for the first event, 2 for the second, etc.

returns nil in case of an error


Parameters:
integer id
the id of the event, whose EventIdenrifier you want to retrieve; 1, the first event; 2, the second event, etc


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetLastCheckfunctionState

Lua: boolean check_state, number last_statechange_precise_time = ultraschall.EventManager_GetLastCheckfunctionState(integer id)

returns the last state the eventcheck-function returned the last time it was called; of a certain registered event in the EventManager. State is requested by number-id, with 1 for the first event, 2 for the second, etc.

returns nil in case of an error; nil and time, if the EventCheck-function didn't return a boolean


Parameters:
integer id
the id of the event, whose eventcheckfunction-retval you want to retrieve; 1, the first event; 2, the second event, etc


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetLastCheckfunctionState2

Lua: boolean check_state, number last_statechange_precise_time = ultraschall.EventManager_GetLastCheckfunctionState2(string EventIdentifier)

returns the last state the eventcheck-function returned the last time it was called; of a certain registered event in the EventManager. State is requested by EventIdentifier

returns nil in case of an error; nil and time, if the EventCheck-function didn't return a boolean


Parameters:
string EventIdentifier
the EventIdentifier of the event, whose last checkfunction-state you want to retrieve


^ Reaper version 5.982 Ultraschall version 4.00EventManager_GetLastUpdateTime

Lua: string datetime, number precise_time = ultraschall.EventManager_GetLastUpdateTime()

Returns the last time, the eventlist in the EventManager had been updated in any way.


Returnvalues:
string datetime
the date and time of the last update, as returned by os.date()
number precise_time
the last update time as number, as returned by reaper.time_precise()


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetPausedState

Lua: boolean paused_state = ultraschall.EventManager_GetPausedState(integer id)

returns, if a certain event, currently registered in the EventManager, is paused(true) or not(false) State is requested by number-id, with 1 for the first event, 2 for the second, etc.

returns nil in case of an error


Parameters:
integer id
the id of the event, whose paused-state you want to retrieve; 1, the first event; 2, the second event, etc


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetPausedState2

Lua: boolean paused_state = ultraschall.EventManager_GetPausedState2(string EventIdentifier)

returns, if a certain event, currently registered in the EventManager, is paused(true) or not(false). State is requested by EventIdentifier.

returns nil in case of an error


Parameters:
string EventIdentifier
the identifier of the registered event, whose pause state you want to retrieve


^ Reaper version 5.965 Ultraschall version 4.00EventManager_GetRegisteredEventID

Lua: integer id = ultraschall.EventManager_GetRegisteredEventID(string EventIdentifier)

returns the id of a registered event, meaning 1, if it's the first event, 2 if it's the second, etc

It is the position within all events currently registered within the EventManager.

returns nil in case of an error


Parameters:
string EventIdentifier
the EventIdentifier of the event, whose id you want to retrieve


^ Reaper version 5.982 Ultraschall version 4.00EventManager_IsValidEventIdentifier

Lua: boolean valid, boolean valid_inuse = ultraschall.EventManager_IsValidEventIdentifier(string event_identifier)

Checks, if a string is a valid EventIdentifier (valid) and currently registered with an event(valid_inuse) in the Ultraschall-EventManager-checking-queue.

returns false in case of an error


Returnvalues:
boolean valid
true, valid EventIdentifier; false, no valid EventIdentifier
boolean valid_inuse
true, valid EventIdentifier, which is currently registered and in use by the EventManager; false, no currently registered EventIdentifier

Parameters:
string event_identifier
the unique identifier of the registered event, that you want to check


^ Reaper version 5.982 Ultraschall version 4.00EventManager_PauseEvent

Lua: boolean retval = ultraschall.EventManager_PauseEvent(string event_identifier)

Pauses a registered event in the Ultraschall Event Manager-checking-queue.

returns false in case of an error


Returnvalues:
boolean retval
true, pausing was successful; false, pausing was unsuccessful

Parameters:
string event_identifier
the unique identifier of the registered event, which you want to pause in the EventManager


^ Reaper version 5.982 Ultraschall version 4.00EventManager_RemoveAllEvents_Script

Lua: boolean retval = ultraschall.EventManager_RemoveAllEvents_Script(string ScriptIdentifier)

Removes all registered events from a script with a certain ScriptIdentifier in the Ultraschall Event Manager-checking-queue.

returns false in case of an error


Returnvalues:
boolean retval
true, removing was successful; false, removing was unsuccessful

Parameters:
string ScriptIdentifier
the unique identifier of the registered event, which you want to remove from the EventManager


^ Reaper version 5.982 Ultraschall version 4.00EventManager_RemoveEvent

Lua: boolean retval = ultraschall.EventManager_RemoveEvent(string event_identifier)

Removes a new event to the Ultraschall Event Manager-checking-queue.

returns false in case of an error


Returnvalues:
boolean retval
true, removing was successful; false, removing was unsuccessful

Parameters:
string event_identifier
the unique identifier of the registered event, which you want to remove from the EventManager


^ Reaper version 5.982 Ultraschall version 4.00EventManager_RemoveStartupEvent

Lua: boolean retval = ultraschall.EventManager_RemoveStartupEvent(string event_identifier)

Removes a startup-event from the config-file of the Ultraschall Event Manager.

returns false in case of an error


Returnvalues:
boolean retval
true, removing was successful; false, removing was unsuccessful

Parameters:
string event_identifier
the unique identifier of the startup event, which you want to remove from the EventManager-startup-procedure


^ Reaper version 5.982 Ultraschall version 4.00EventManager_RemoveStartupEvent2

Lua: boolean retval = ultraschall.EventManager_RemoveStartupEvent2(integer id)

Removes a startup-event from the config-file of the Ultraschall Event Manager.

returns false in case of an error


Returnvalues:
boolean retval
true, removing was successful; false, removing was unsuccessful

Parameters:
string event_identifier
the unique identifier of the startup event, which you want to remove from the EventManager-startup-procedure


^ Reaper version 5.982 Ultraschall version 4.00EventManager_ResumeEvent

Lua: boolean retval = ultraschall.EventManager_ResumeEvent(string event_identifier)

Resumes a registered and paused event in the Ultraschall Event Manager-checking-queue.

returns false in case of an error


Returnvalues:
boolean retval
true, resuming was successful; false, resuming was unsuccessful

Parameters:
string event_identifier
the unique identifier of the registered event, which you want to resume in the EventManager


^ Reaper version 5.982 Ultraschall version 4.00EventManager_SetEvent

Lua: boolean retval = ultraschall.EventManager_SetEvent(string EventIdentifier, optional string EventName, optional integer CheckAllXSeconds, optional integer CheckForXSeconds, optional boolean StartActionsOnceDuringTrue, optional boolean EventPaused, optional function CheckFunction, optional table Actions)

Sets the attributes of an already added event in the Ultraschall Event Manager-checking-queue.

returns nil in case of an error


Returnvalues:
boolean retval
true, setting was successful; false, setting wasn't successful

Parameters:
string EventIdentifier
the EventIdentifier of the registered event, which you want to set
optional string EventName
a name for the event, which you can choose freely; duplicated eventnames are allowed; nil, keep the old name
optional integer CheckAllXSeconds
only check all x seconds; 0, for constant checking; nil, keep the old value
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
optional integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed; nil, keep the old value
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
optional boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
   nil, keep the old value
optional boolean EventPaused
false, register the event and check for it immediately; true, register the event but don't check for it yet; nil, keep the old value
optional function CheckFunction
the function, which shall check if the event occurred; nil, keep the old function
this function must return true if the event occurred and false, if not
No global variables allowed! Instead, the eventmanager will pass to the function as first parameter a table which can be used for storing information
optional table Actions
a table which holds all actions and their accompanying sections, who shall be run when the event occurred; nil, keep the old actionlist
each entry of the table must be of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

You can have as many actions as you like, but be aware, that running too many actions may delay further eventchecking!


^ Reaper version 5.982 Ultraschall version 4.00EventManager_SetStartupEvent

Lua: string event_identifier = ultraschall.EventManager_SetStartupEvent(string EventIdentifier, optional string EventName, optional integer CheckAllXSeconds, optional integer CheckForXSeconds, optional boolean StartActionsOnceDuringTrue, optional boolean EventPaused, optional function CheckFunction, optional table Actions)

Sets an already existing startupevent, that shall be automatically run at startup of the Ultraschall Event Manager.

That means, if you start the EventManager, it will be started automatically to the EventManager-checking-queue, without the need of registering it by hand.

returns nil in case of an error


Returnvalues:
string event_identifier
the unique identifier for this registered event, which can be used later for setting, deleting, etc

Parameters:
string EventIdentifier
the EventIdentifier of the startup-event, which you want to set
optional string EventName
a name for the event, which you can choose freely; duplicated eventnames are allowed; nil, to keep current name
optional integer CheckAllXSeconds
only check all x seconds; 0, for constant checking; nil, to keep current value
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
optional integer CheckForXSeconds
only check for x seconds; 0, check until the event is removed; nil, to keep current value
this value will be used as approximate time, not necessarily exact. That means, 2 seconds given may be 2.5 in some cases!
This is due general limitations with backgroundscripts.
optional boolean StartActionsOnceDuringTrue
if the event occurred:
   true, run the actions only once;
   false, run until the CheckFunction returns false again
   nil, to keep current value
optional boolean EventPaused
false, register the event and check for it immediately; true, register the event but don't check for it yet; nil, to keep current value
optional function CheckFunction
the function, which shall check if the event occurred; nil, to keep current function
this function must return true if the event occurred and false, if not
No global variables allowed! Instead, the eventmanager will pass to the function as first parameter a table which can be used for storing information
optional table Actions
a table which holds all actions and their accompanying sections, who shall be run when the event occurred; nil, to keep current actionlist
each entry of the table must be of the format "actioncommandid,section", e.g.:

Actions[1]="1007,0"
Actions[2]="1012,0"

You can have as many actions as you like, but be aware, that running too many actions may delay further eventchecking!


^ Reaper version 5.982 Ultraschall version 4.00EventManager_Start

Lua: boolean retval = ultraschall.EventManager_Start()

Starts the Ultraschall-EventManager, if it has not been started yet.


Returnvalues:
boolean retval
true, EventManager has been started successfully; false, EventManager couldn't be started


^ Reaper version 5.982 Ultraschall version 4.00EventManager_Stop

Lua: ultraschall.EventManager_Stop(optional boolean force, optional string ScriptIdentifier)

Unregisters the current script; will stop the EventManager if no scripts are registered anymore to the EventManager.

You can use the parameter force to force stopping of the EventManager immediately.


Parameters:
optional boolean force
true, stops the EventManager, even if other scripts have registered events to it; false or nil, don't force stop
optional string ScriptIdentifier
if you want to unregister events from a different script, pass here the ScriptIdentifier of this script; nil, use the ScriptIdentifier of the current script


^ Reaper version 6.10 Ultraschall version 4.2CountFXFromFXStateChunk

Lua: integer count_of_fx= ultraschall.CountFXFromFXStateChunk(string FXStateChunk)

count the number of fx available in an FXStateChunk

returns nil in case of an error

Returnvalues:
integer count_of_fx
the number of fx within the FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk in which you want to count the fx


^ Reaper version 6.02 Ultraschall version 4.00CountFXStateChunksInStateChunk

Lua: integer count_of_takefx_statechunks, integer count_of_trackfx_statechunks = ultraschall.CountFXStateChunksInStateChunk(string StateChunk)

Counts all FXStateChunks within a StateChunk.
You can pass ItemStateChunks, TrackStateChunks and ProjectStateChunks.

returns -1 in case of an error.

Returnvalues:
integer count_of_takefx_statechunks
the number of take-fx-StateChunks within the StateChunk. When passing Track/ProjectStateChunks, it returns number of all FXStateChunks from all Takes within the StateChunk
integer count_of_trackfx_statechunks
the number of TrackFX-StateChunks; each track alawys has a single one, so it should match the number of tracks within the StateChunk; 0, if you pass a ItemStateChunk

Parameters:
string StateChunk
the StateChunk, whose count of FXStateChunks you want to retrieve


^ Reaper version 6.02 Ultraschall version 4.00GetAllRFXChainfilenames

Lua: integer count_of_RFXChainfiles, array RFXChainfiles = ultraschall.GetAllRFXChainfilenames()

Returns all available RFXChainfiles in the folder ResourcePath/FXChains

Returnvalues:
integer count_of_RFXChainfiles
the number of available RFXChainFiles
array RFXChainfiles
the filenames of the RFXChainfiles


^ Reaper version 5.975 Ultraschall version 4.00GetFXStateChunk

Lua: string FXStateChunk, integer linenumber = ultraschall.GetFXStateChunk(string StateChunk, optional integer TakeFXChain_id)

Returns an FXStateChunk from a TrackStateChunk or a MediaItemStateChunk.

An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

Returns nil in case of an error or if no FXStateChunk has been found.

Returnvalues:
string FXStateChunk
the FXStateChunk, stored in the StateChunk
integer linenumber
returns the first linenumber, at which the found FXStateChunk starts in the StateChunk

Parameters:
string StateChunk
the StateChunk, from which you want to retrieve the FXStateChunk
optional integer TakeFXChain_id
when using MediaItemStateChunks, this allows you to choose the take of which you want the FXChain; default is 1


^ Reaper version 5.975 Ultraschall version 4.2IsValidFXStateChunk

Lua: boolean retval = ultraschall.IsValidFXStateChunk(string StateChunk)

Returns, if a StateChunk is a valid FXStateChunk.
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem or inputFX.

Returns false in case of an error

Returnvalues:
boolean retval
true, it is a valid FXStateChunk; false, it is not

Parameters:
string StateChunk
the StateChunk, which you want to check, whether it's a valid FXStateChunk


^ Reaper version 6.02 Ultraschall version 4.00LoadFXStateChunkFromRFXChainFile

Lua: string FXStateChunk = ultraschall.LoadFXStateChunkFromRFXChainFile(string filename, integer trackfx_or_takefx)

Loads an FXStateChunk from an RFXChain-file.

If you don't give a path, it will try to load the file from the folder ResourcePath/FXChains.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the loaded FXStateChunk; nil, in case of an error

Parameters:
string filename
the filename of the RFXChain-file(must include ".RfxChain"); omit the path to load it from the folder ResourcePath/FXChains
integer trackfx_or_takefx
0, return the FXStateChunk as Track-FXStateChunk; 1, return the FXStateChunk as Take-FXStateChunk


^ Reaper version 6.02 Ultraschall version 4.00RemoveFXStateChunkFromItemStateChunk

Lua: string alteredItemStateChunk = ultraschall.RemoveFXStateChunkFromItemStateChunk(string ItemStateChunk, integer take_id)

Removes a certain Take-FXStateChunk from an ItemStateChunk.

Returns nil in case of failure.

Returnvalues:
string alteredItemStateChunk
the StateChunk, from which the FXStateChunk was removed

Parameters:
string ItemStateChunk
the ItemStateChunk, from which you want to remove an FXStateChunk
integer take_id
the take, whose FXStateChunk you want to remove


^ Reaper version 6.02 Ultraschall version 4.00RemoveFXStateChunkFromTrackStateChunk

Lua: string altered_TrackStateChunk = ultraschall.RemoveFXStateChunkFromTrackStateChunk(string TrackStateChunk)

Clears the FXChain from a TrackStateChunk

returns nil in case of an error.

Returnvalues:
string altered_TrackStateChunk
the TrackStateChunk, cleared of the Track-FXStateChunk

Parameters:
string TrackStateChunk
the TrackStateChunk, whose FXStateChunk you want to remove


^ Reaper version 6.02 Ultraschall version 4.00SaveFXStateChunkAsRFXChainfile

Lua: integer retval = ultraschall.SaveFXStateChunkAsRFXChainfile(string filename, string FXStateChunk)

Loads an FXStateChunk from an RFXChain-file.

If you don't give a path, it will try to load the file from the folder ResourcePath/FXChains.

returns -1 in case of an error

Returnvalues:
integer retval
-1 in case of failure, 1 in case of success

Parameters:
string filename
the filename of the output-RFXChain-file(must include ".RfxChain"); omit the path to save it into the folder ResourcePath/FXChains
string FXStateChunk
the FXStateChunk, which you want to set into the TrackStateChunk


^ Reaper version 5.979 Ultraschall version 4.00SetFXStateChunk

Lua: boolean retval, optional string alteredStateChunk = ultraschall.SetFXStateChunk(string StateChunk, string FXStateChunk, optional integer TakeFXChain_id)

Adds/replaces FXStateChunk to/in a TrackStateChunk or a MediaItemStateChunk.

returns false in case of an error

Returnvalues:
boolean retval
true, if setting fxstatechunk was successful; false, if setting was unsuccessful
optional string alteredStateChunk
the altered StateChunk

Parameters:
string StateChunk
the TrackStateChunk, into which you want to set the FXChain
string FXStateChunk
the FXStateChunk, which you want to set into the TrackStateChunk
optional integer TakeFXChain_id
when using MediaItemStateChunks, this allows you to choose the take of which you want the FXChain; default is 1


^ Reaper version 6.02 Ultraschall version 4.2GetDocked_FXStateChunk

Lua: integer dockstate = ultraschall.GetDocked_FXStateChunk(string FXStateChunk, integer fxid)

returns the DOCKED-entryvalues from an FXStateChunk.

returns nil in case of an error

Returnvalues:
integer dockstate
0, undocked; 1, docked

Parameters:
string FXStateChunk
the FXStateChunk, whose dockstate you want to get


^ Reaper version 6.02 Ultraschall version 4.2GetFXBypass_FXStateChunk

Lua: integer bypass, integer offline, integer unknown = ultraschall.GetFXBypass_FXStateChunk(string FXStateChunk, integer fxid)

returns the BYPASS-entryvalues of a specific fx from an FXStateChunk, like bypass and online-state..

returns nil in case of an error

Returnvalues:
integer bypass
0, non-bypassed; 1, bypassed
integer offline
0, online; 1, offline
integer unknown
unknown; default is 0

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return the BYPASS-entry
integer fxid
the fx, whose BYPASS-entryvalues you want to return


^ Reaper version 6.02 Ultraschall version 4.2GetFXComment_FXStateChunk

Lua: string comment = ultraschall.GetFXComment_FXStateChunk(string FXStateChunk, integer fxid)

returns the fx-comment of a specific fx from an FXStateChunk

will return "" if no comment exists

returns nil in case of an error

Returnvalues:
string comment
the comment as stored for this specific fx; "", if no comment exists

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return a specific fx-comment
integer fxid
the fx, whose comment you want to return


^ Reaper version 6.02 Ultraschall version 4.2GetFXFloatPos_FXStateChunk

Lua: boolean floating, integer x, integer y, integer width, integer height = ultraschall.GetFXFloatPos_FXStateChunk(string FXStateChunk, integer fxid)

returns the FLOATPOS/FLOAT-entryvalues of a specific fx from an FXStateChunk, like float-state and float-coordinates.

If all coordinates of the floating fx-window are 0, then the fx-window was never in float-state, yet.

There is only one of the FLOATPOS/FLOAT-entries present at any time.
FLOATPOS, when the fx-window is not floating
FLOAT, when the fx-window is floating.

returns nil in case of an error

Returnvalues:
boolean floating
true, fx-window is floating; false, fx-window isn't floating
integer x
the x-position of the floating window; 0, if it hasn't been floating yet
integer y
the y-position of the floating window; 0, if it hasn't been floating yet
integer width
the width of the floating window; 0, if it hasn't been floating yet
integer height
the height of the floating window; 0, if it hasn't been floating yet

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return the FLOAT/FLOATPOS-entry
integer fxid
the fx, whose FLOAT/FLOATPOS-entryvalues you want to return


^ Reaper version 6.10 Ultraschall version 4.2GetFXFromFXStateChunk

Lua: string fx_lines, integer startoffset, integer endoffset = ultraschall.GetFXFromFXStateChunk(string FXStateChunk, integer fxindex)

returns the statechunk-lines of fx with fxindex from an FXStateChunk

It also returns the start and endoffset of these lines, so you can manipulate these lines and replace them in the
original FXStateChunk, by replacing the part between start and endoffset with your altered lines.

returns nil in case of an error

Returnvalues:
string fx_lines
the statechunk-lines associated with this fx
integer startoffset
the startoffset in bytes of these lines within the FXStateChunk
integer endoffset
the endoffset in bytes of these lines within the FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk from which you want to retrieve the fx's-lines
integer fxindex
the index of the fx, whose statechunk lines you want to retrieve; with 1 for the first


^ Reaper version 6.02 Ultraschall version 4.2GetFXGuid_FXStateChunk

Lua: string guid = ultraschall.GetFXGuid_FXStateChunk(string FXStateChunk, integer fxid)

returns the FXID-entryvalues of a specific fx from an FXStateChunk, which is the guid of the fx.

returns nil in case of an error

Returnvalues:
string guid
the guid of the fx

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return the guid-entry
integer fxid
the fx, whose guid you want to return


^ Reaper version 6.02 Ultraschall version 4.2GetFXMidiPreset_FXStateChunk

Lua: integer midi_preset = ultraschall.GetFXMidiPreset_FXStateChunk(string FXStateChunk, integer fxid)

returns the MIDIPRESET-entryvalues of a specific fx from an FXStateChunk as set by the +-button->Link to MIDI program change-menuentry in the FX-window of the visible plugin.

returns nil in case of an error

Returnvalues:
integer midi_preset
0, No Link; 17, Link all channels sequentially; 1-16, MIDI-channel 1-16

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return the MIDIPRESET-entry
integer fxid
the fx, whose MIDIPRESET-entryvalues you want to return


^ Reaper version 6.02 Ultraschall version 4.2GetFXSettingsString_FXLines

Lua: string fx_statestring_base64, string fx_statestring = ultraschall.GetFXSettingsString_FXLines(string fx_lines)

Returns the fx-states-string of a fx, as stored as an base64-string.byte It returns its decoded and encoded version of it.

Use GetFXFromFXStateChunk to get the requested parameter "fx_lines"

returns nil in case of an error


Returnvalues:
string fx_statestring_base64
the base64-version of the state-string, which holds all fx-settings of the fx
string fx_statestring
the decoded binary-version of the state-string, which holds all fx-settings of the fx

Parameters:
string fx_lines
the statechunk-lines of an fx, as returned by the function GetFXFromFXStateChunk()


^ Reaper version 6.02 Ultraschall version 4.2GetFXWak_FXStateChunk

Lua: integer keyboard_input_2_plugin, integer fx_embed_state = ultraschall.GetFXWak_FXStateChunk(string FXStateChunk, integer fxid)

returns the WAK-entryvalues of a specific fx from an FXStateChunk, as set by the +-button->Send all keyboard input to plugin-menuentry in the FX-window of the visible plugin.

returns nil in case of an error

Returnvalues:
integer keyboard_input_2_plugin
0, don't send all the keyboard-input to plugin; 1, send all keyboard-input to plugin
integer fx_embed_state
set embedding of the fx; &1=TCP, &2=MCP

Parameters:
string FXStateChunk
the FXStateChunk, from whose fx you want to return the WAK-entry
integer fxid
the fx, whose WAK-entryvalues you want to return


^ Reaper version 6.02 Ultraschall version 4.2GetLastSel_FXStateChunk

Lua: integer last_selected_fx = ultraschall.GetLastSel_FXStateChunk(string FXStateChunk, integer fxid)

returns the LASTSEL-entryvalues from an FXStateChunk.

returns nil in case of an error

Returnvalues:
integer last_selected_fx
the last selected fx; 1, the first fx; 2, the second fx; 3, the third fx

Parameters:
string FXStateChunk
the FXStateChunk, whose last-selected-fx you want to get


^ Reaper version 6.02 Ultraschall version 4.2GetShow_FXStateChunk

Lua: integer showstate = ultraschall.GetShow_FXStateChunk(string FXStateChunk, integer fxid)

returns the SHOW-entryvalues from an FXStateChunk.

This shows, whether the fxchain is currently shown and which fx is visible in Reaper's UI.

returns nil in case of an error

Returnvalues:
integer shownstate
0, the fx-chain is not shown; 1, first fx is shown; 2, second fx is shown, etc

Parameters:
string FXStateChunk
the FXStateChunk, whose show-state you want to get


^ Reaper version 6.10 Ultraschall version 4.2GetTakeFXComment

Lua: string comment = ultraschall.GetTakeFXComment(MediaItem item, integer takeid, integer fxid)

returns the comment of a take-fx

returns nil in case of an error

Returnvalues:
string comment
the comment of a track-fx

Parameters:
MediaItem item
the mediaitem, whose takefx-comment you want to request
integer take_id
the id of the take, whose takefx-comment you want to request
integer fxid
the id of the fx, whose comment you want to have


^ Reaper version 6.11 Ultraschall version 4.1GetTakeFX_AlternativeName

Lua: string alternative_fx_name = ultraschall.GetTakeFX_AlternativeName(integer tracknumber, integer take_id, integer fx_id)

Returns the alternative name of a specific takefx.

Returns nil in case of an error

Returnvalues:
string alternative_fx_name
the alternative fx-name set for this fx


^ Reaper version 6.10 Ultraschall version 4.2GetTrackFXComment

Lua: string comment = ultraschall.GetTrackFXComment(MediaTrack track, integer fxid)

returns the comment of a track-fx

returns nil in case of an error

Returnvalues:
string comment
the comment of a track-fx

Parameters:
MediaTrack track
the mediatrack, of which you want to request a trackfx's comment
integer fxid
the id of the fx, whose comment you want to have


^ Reaper version 6.11 Ultraschall version 4.1GetTrackFX_AlternativeName

Lua: string alternative_fx_name = ultraschall.GetTrackFX_AlternativeName(integer tracknumber, integer fx_id)

Returns the alternative name of a specific trackfx.

Returns nil in case of an error

Returnvalues:
string alternative_fx_name
the alternative fx-name set for this fx


^ Reaper version 6.02 Ultraschall version 4.2GetWndRect_FXStateChunk

Lua: integer x, integer y, integer width, integer height = ultraschall.GetWndRect_FXStateChunk(string FXStateChunk, integer fxid)

returns the WNDRECT-entryvalues from an FXStateChunk.

These are the window-positions of the fx-chain, when the window is floating.

returns nil in case of an error

Returnvalues:
integer x
the x-position of the floating window; 0, if it hasn't been floating yet
integer y
the y-position of the floating window; 0, if it hasn't been floating yet
integer width
the width of the floating window; 0, if it hasn't been floating yet
integer height
the height of the floating window; 0, if it hasn't been floating yet

Parameters:
string FXStateChunk
the FXStateChunk, whose floating-window-position you want to get


^ Reaper version 6.02 Ultraschall version 4.1GetFocusedFX

Lua: integer retval, integer tracknumber, integer fxidx, integer itemnumber, integer takeidx, MediaTrack track, optional MediaItem item, optional MediaItemTake take = ultraschall.GetFocusedFX()

Returns the focused FX

Returnvalues:
integer retval
0, if no FX window has focus
1, if a track FX window has focus or was the last focused and still open
2, if an item FX window has focus or was the last focused and still open
integer tracknumber
tracknumber; 0, master track; 1, track 1; etc.
integer fxidx
the index of the FX; 1-based
integer itemnumber
-1, if it's a track-fx; 1 and higher, the mediaitem-number
integer takeidx
-1, if it's a track-fx; 1 and higher, the take-number
MediaTrack track
the MediaTrack-object
optional MediaItem item
the MediaItem, if take-fx
optional MediaItemTake take
the MediaItem-Take, if take-fx


^ Reaper version 6.02 Ultraschall version 4.1GetLastTouchedFX

Lua: boolean retval, integer sourcetype, integer track_take_number, integer fxnumber, integer paramnumber, integer takeID, optional MediaTrack track, optional MediaItemTake take = ultraschall.GetLastTouchedFX()

Returns the last touched FX

Note: Does not return last touched monitoring-FX!

Returnvalues:
boolean retval
true, valid FX; false, no valid FX
integer sourcetype
0, takeFX; 1, trackFX
integer track_take_number
the track or takenumber(see sourcetype-retval); 1-based
integer fxnumber
the number of the fx; 1-based
integer paramnumber
the number of the parameter; 1-based
integer takeID
the number of the take; 1-based; -1, if takeFX
optional MediaTrack track
the track of the TrackFX
optional MediaItemTake take
the take of the TakeFX


^ Reaper version 6.02 SWS version 2.10.0.1 Ultraschall version 4.00GetRecentFX

Lua: integer count_of_RecentFX, array RecentFX = ultraschall.GetRecentFX()

Returns the recent fx-list

Returnvalues:
integer count_of_RecentFX
the number of available recent fx
array RecentFX
the names of the recent fx


^ Reaper version 6.05 Ultraschall version 4.2InputFX_AddByName

Lua: integer retval = ultraschall.InputFX_AddByName(string fxname, boolean always_new_instance, optional integer tracknumber)

Adds an FX as monitoring FX.

returns -1 in case of an error

Returnvalues:
integer retval
the index of the newly inserted fx or the index of the already existing fx; -1, in case of an error

Parameters:
string fxname
the name of the fx to be inserted
boolean always_new_instance
true, always add a new instance of the fx; false, only add if there's none yet
optional integer tracknumber
the tracknumber, to whose inputFX the fx shall be added; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_CopyFX

Lua: boolean retval = ultraschall.InputFX_CopyFX(integer old_fxindex, integer new_fxindex, optional integer tracknumber_source, optional integer tracknumber_target)

Copies a monitoring-fx and inserts it at a new position

returns -1 in case of an error

Returnvalues:
integer retval
the index of the inserted fx(in case of being different from new_fxindex); -1, in case of an error; 1-based

Parameters:
integer old_fxindex
the index of the input-fx to be copied; 1-based
integer new_fxindex
the position of the newly inserted input-fx; 1-based
optional integer tracknumber_source
the tracknumber of the track, from whose inputFX you want to move the fx; 1-based; nil, master-track
optional integer tracknumber_target
the tracknumber of the track, to which you want to move the inputFX; 1-based; nil, master-track    


^ Reaper version 6.05 Ultraschall version 4.2InputFX_CopyFXFromTakeFX

Lua: integer dest_fx = ultraschall.InputFX_CopyFXFromTakeFX(MediaItem_Take take, integer src_fx, integer dest_fx, optional integer dest_tracknumber)

copies a takeFX to monitoringFX

returns -1 in case of an error

Returnvalues:
integer dest_fx
the index of the inserted FX, just in case it differs; 1-based

Parameters:
MediaItem_Take take
the take, from which you want to copy the takeFX
integer src_fx
the index takeFX that shall be copied; 1-based
integer dest_fx
the index, at which you want to insert the fx into the monitoring FXChain; 1-based
optional integer dest_tracknumber
the tracknumber, to which you want to copy a new inputFX; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_CopyFXFromTrackFX

Lua: integer retval = ultraschall.InputFX_CopyFXFromTrackFX(MediaTrack track, integer old_fxindex, integer new_fxindex, optional integer tracknumberInputFX)

Copies a trackfx and inserts it as monitoring-fx at a certain position

returns -1 in case of an error

Returnvalues:
integer retval
the index of the inserted fx(in case of being different from new_fxindex); -1, in case of an error; 1-based

Parameters:
MediaTrack track
the track from which you want to copy a trackfx
integer old_fxindex
the index of the track-fx to be copied; 1-based
integer new_fxindex
the position of the newly inserted input-fx; 1-based
optional integer tracknumberInputFX
the tracknumber, to whose inputFX the fx shall be copied; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_CopyFXToTakeFX

Lua: integer dest_fx = ultraschall.InputFX_CopyFXToTakeFX(integer src_fx, MediaItem_Take take, integer dest_fx, optional integer src_tracknumber)

copies a monitoring-fx to a takeFX

returns -1 in case of an error

Returnvalues:
integer dest_fx
the index of the inserted FX, just in case it differs; 1-based

Parameters:
integer src_fx
the index inputFX that shall be copied; 1-based
MediaItem_Take take
the take, into which you want to insert the fx as takeFX
integer dest_fx
the index, at which you want to insert the fx; 1-based
optional integer src_tracknumber
the tracknumber, whose inputFX you want to copy; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_CopyFXToTrackFX

Lua: integer retval = ultraschall.InputFX_CopyFXToTrackFX(integer old_fxindex, MediaTrack track, integer new_fxindex, optional integer tracknumberInputFX)

Copies a monitoring-fx and inserts it as trackfx at a certain position

returns -1 in case of an error

Returnvalues:
integer retval
the index of the inserted fx(in case of being different from new_fxindex); -1, in case of an error

Parameters:
integer old_fxindex
the index of the monitoring-fx to be copied; 1-based
MediaTrack track
the track into which you want to insert the trackFX
integer new_fxindex
the position of the newly inserted track-fx; 1-based
optional integer tracknumberInputFX
the tracknumber, from whose inputFX the fx shall be copied from; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_Delete

Lua: boolean retval = ultraschall.InputFX_Delete(integer fxindex, optional integer tracknumber)

removes a certain monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, removing was successful; false, removing was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx to be deleted; 1-based
optional integer tracknumber
the tracknumber, whose inputFX shall be deleted; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_EndParamEdit

Lua: boolean retval = ultraschall.InputFX_EndParamEdit(integer fxindex, integer paramindex, optional integer tracknumber)

This ends the capture of a parameter(e.g when finished writing automation)

returns false in case of an error

Returnvalues:
boolean retval
true, unknown; false, unknown

Parameters:
integer fxindex
the index of the monitoring-fx
integer paramindex
the index of the parameter of the monitoring-fx
optional integer tracknumber
the tracknumber, whose inputFX-parameter shall be ended in editing; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_FormatParamValue

Lua: boolean retval, string formatted_value = ultraschall.InputFX_FormatParamValue(integer fxindex, integer paramindex, number value, optional integer tracknumber)

You can take a value and format it in the style of the used format of a specific parameter, like the frequency(to Hz), gain(to dB) with ReaEQ or bypass(normal, bypasses), wet with ReaTune, etc.

Note: only works with FX that support Cockos VST extensions.

returns false in case of an error

Returnvalues:
boolean retval
true, formatting was successful; false, formatting was unsuccessful(no such fx, parameter, no support for Cockos VST extension
string formatted_value
the value in the format of the parameter; "", if not available

Parameters:
integer fxindex
the index of the fx; 1-based
integer paramindex
the parameter, whose formatting-style you want to applied to value; 1-based
number value
the value you want to have formatted in the style of the parameter
optional integer tracknumber
the tracknumber, whose inputFX-parameter you want to format; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_FormatParamValueNormalized

Lua: boolean retval, string formatted_value = ultraschall.InputFX_FormatParamValueNormalized(integer fxindex, integer paramindex, number value, optional integer tracknumber)

You can take a value and format it in the style of the used format of a specific parameter, like the frequency(to Hz), gain(to dB) with ReaEQ or bypass(normal, bypasses), wet with ReaTune, etc.
The value will be normalized.

Note: only works with FX that support Cockos VST extensions.

returns false in case of an error

Returnvalues:
boolean retval
true, formatting was successful; false, formatting was unsuccessful(no such fx, parameter, no support for Cockos VST extension
string formatted_value
the value in the format of the parameter; "", if not available

Parameters:
integer fxindex
the index of the fx; 1-based
integer paramindex
the parameter, whose formatting-style you want to applied to value; 1-based
number value
the value you want to have formatted in the style of the parameter
optional integer tracknumber
the tracknumber, whose inputFX-parameter you want to get formatted and normalized; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetChainVisible

Lua: boolean inputfx_chain_visible, integer visible_inputfx = ultraschall.InputFX_GetChainVisible(optional integer tracknumber)

returns if the monitoring-fx-chain is visible and index of the currently visible monitoring-fx

returns nil in case of an error

Returnvalues:
boolean inputfx_chain_visible
true, fxchain is visible; false, fxchain is not visible
integer visible_inputfx
the index of the currently visible monitoring-fx; -1, if nothing is visible; 1-based    

Parameters:
optional integer tracknumber
the tracknumber, whose inputFX-chain-visibility you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.10 Ultraschall version 4.2InputFX_GetComment

Lua: string comment = ultraschall.InputFX_GetComment(integer fxid)

returns the comment of an input-fx

returns nil in case of an error

Returnvalues:
string comment
the comment of a track-fx

Parameters:
integer fxid
the id of the fx, whose comment you want to have


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetCount

Lua: integer monitoring_fx_count = ultraschall.InputFX_GetCount(optional integer tracknumber)

counts the available monitoring-fx

returns -1 in case of an error

Returnvalues:
integer monitoring_fx_count
the number of available monitoring-fx    

Parameters:
optional integer tracknumber
the tracknumber, whose inputFX you want to count; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetEQ

Lua: integer index = ultraschall.InputFX_GetEQ(boolean instantiate, optional integer tracknumber)

Get the index of the first ReaEQ-instance in the monitoringFX, if available.

Optionally add a new instance if ReaEQ isn't existing yet in the monitoring-fx-chain.

returns -1 in case of an error

Returnvalues:
integer index_of_reaeq
the index of the first instance of ReaEQ in the monitoringFX; 0, if no ReaEQ is in the monitoringFX; -1, in case of an error

Parameters:
boolean instantiate
true, add ReaEQ into monitoring-fx if not existing yet; false, don't add a ReaEQ-instance if not existing in monitoring-FXChain yet
optional integer tracknumber
the tracknumber, whose inputFX-eq-position you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetEQBandEnabled

Lua: boolean enabled = ultraschall.InputFX_GetEQBandEnabled(integer fxindex, integer bandtype, integer bandidx, optional integer tracknumber)

Gets the enable or disable-state of a ReaEQ band of a monitoring-fx.

returns false in case of an error

Returnvalues:
boolean enabled
true, band is enabled; false, band is disabled

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer bandtype
the bandtype of the band to change;
0, lhipass
1, loshelf
2, band
3, notch
4, hishelf
5, lopass
integer bandidx
0, first band matching bandtype; 1, 2nd band matching bandtype, etc.
optional integer tracknumber
the tracknumber, whose inputFX-EQ-Band-enabled-state you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetEQParam

Lua: boolean retval, number bandtype, number bandidx, number paramtype, number normval = ultraschall.InputFX_GetEQParam(integer fxindex, integer paramidx, optional integer tracknumber)

Gets the states and values of an EQ-parameter of a ReaEQ-instance in monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, if it's a ReaEQ-instance; false, is not a ReaEQ-instance or in case of an error
integer bandtype
the bandtype of the band to change;
-1, master gain
0, lhipass
1, loshelf
2, band
3, notch
4, hishelf
5, lopass
integer bandidx
0, first band matching bandtype; 1, 2nd band matching bandtype, etc.
number paramtype
0, freq; 1, gain; 2, Q
number normval
the normalized value

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramidx
the parameter whose eq-states you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-eq-param you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetEnabled

Lua: boolean inputfx_enabled = ultraschall.InputFX_GetEnabled(integer fxindex, optional integer tracknumber)

returns if a certain monitoring-fx is enabled

returns nil in case of an error

Returnvalues:
boolean inputfx_enabled
true, fx is enabled; false, fxchain is not enabled

Parameters:
integer fxindex
the index of the monitoring-fx, whose enabled state you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-enabledness you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetFXChain

Lua: string FXStateChunk = ultraschall.InputFX_GetFXChain(integer fxstatechunk_type, optional integer tracknumber)

Loads the FXStateChunk from the monitoring-fx-chain.

Returns

Returnvalues:
string FXStateChunk
the loaded FXStateChunk; nil, in case of an error

Parameters:
integer fxstatechunk_type
0, return the FXStateChunk as Track-FXStateChunk
1, return the FXStateChunk as Take-FXStateChunk
2, return the FXStateChunk as Track-InputFX-FXStateChunk
optional integer tracknumber
the tracknumber of the track, whose fxinput-chain you want to get
nil or 0, global monitoring-fx; 1 and higher, the inputFX-chain from track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetFXGUID

Lua: string fxguid = ultraschall.InputFX_GetFXGUID(integer fxindex, optional integer tracknumber)

returns the guid of a monitoring-fx

returns nil in case of an error

Returnvalues:
string fxguid
the guid of the monitoring-fx

Parameters:
integer fxindex
the index of the monitoring-fx, whose guid you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-fx-guid you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetFXName

Lua: boolean retval, string fxname = ultraschall.InputFX_GetFXName(integer fxindex, optional integer tracknumber)

returns the name of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, monitoring fx exists; false, no such monitoring-fx exists
string fxname
the name of the monitoring-fx

Parameters:
integer fxindex
the index of the monitoring-fx, whose name you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-fxname you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetFloatingWindow

Lua: HWND inputfx_floating_hwnd = ultraschall.InputFX_GetFloatingWindow(integer fxindex, optional integer tracknumber)

returns the hwnd of a floating monitoring-fx-window

returns nil in case of an error

Returnvalues:
HWND inputfx_floating_hwnd
the hwnd of the floating montitoring fx; nil, if not available

Parameters:
integer fxindex
the index of the monitoring-fx, whose floating-monitoring-fx-hwnd you want to get; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-floating-window-hwnd you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetFormattedParamValue

Lua: boolean retval, string formatted_value = ultraschall.InputFX_GetFormattedParamValue(integer fxindex, integer paramindex, optional integer tracknumber)

Returns the current value of the monitoring-fx's parameter in its formatted style.

returns false in case of an error

Returnvalues:
boolean retval
true, getting was successful; false, getting was unsuccessful
string formatted_value
the value of the formatted parameter; "", if not available

Parameters:
integer fxindex
the index of the fx; 1-based
integer paramindex
the parameter, whose formatted value you want to get; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-parameter-value you want to get as formatted; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetIOSize

Lua: integer retval, optional number inputPins, optional number outputPins = ultraschall.InputFX_GetIOSize(integer fxindex, optional integer tracknumber)

Returns the plugin-type and the input/output-pins available for an inputFX

returns -1 in case of an error

Returnvalues:
integer retval
the plugin-type
-1, no such plugin
0, VSTi
2, JSFX
3, VST
5, Mac AU
6, Video Processor
optional number inputPins
the number of input-pins available
optional number outputPins
the number of output-pins available

Parameters:
integer fxindex
the index of the fx; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-plugintype/in-out-pins you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetNamedConfigParm

Lua: boolean retval, string config_parm_name = ultraschall.InputFX_GetNamedConfigParm(integer fxindex, string parmname, optional integer tracknumber)

gets plug-in specific named configuration value (returns true on success) of a monitoring-fx.

Special values:
'pdc' returns PDC latency.
'in_pin_0' returns name of first input pin (if available),
'out_pin_0' returns name of first output pin (if available), etc.

returns false in case of an error

Returnvalues:
boolean retval
true, name is available; false, name is not available
string config_parm_name
the name of the config parameter

Parameters:
integer fxindex
the index of the fx; 1-based
string parmname
the value of the named config parm you want to get
optional integer tracknumber
the tracknumber, whose inputFX-named-config-parameter-state you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetNumParams

Lua: integer count_params = ultraschall.InputFX_GetNumParams(integer fxindex, optional integer tracknumber)

returns the number of parameters of a monitoring-fx

returns -1 in case of an error

Returnvalues:
integer count_params
the number of parameters of the monitoring-fx

Parameters:
integer fxindex
the index of the monitoring-fx, whose number of parameters you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-fxname you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetOffline

Lua: boolean is_offline = ultraschall.InputFX_GetOffline(integer fxindex)

returns the offline-state of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean is_offline
true, fx is offline; false, fx is not offline

Parameters:
integer fxindex
the index of the monitoring-fx, whose offline-state you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-offline-state you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetOpen

Lua: boolean is_open = ultraschall.InputFX_GetOpen(integer fxindex, optional integer tracknumber)

returns if a monitoring-fx is open(currently visible)

returns false in case of an error

Returnvalues:
boolean is_open
true, fx is visible; false, fx is not visible

Parameters:
integer fxindex
the index of the monitoring-fx, whose visibility-state you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-visibility-state you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetParam

Lua: number curval, number minval, number maxval = ultraschall.InputFX_GetParam(integer fxindex, integer paramindex, optional integer tracknumber)

returns the current, maximum and minimum value of a parameter of a monitoring-fx.

returns nil in case of an error

Returnvalues:
number curval
the current value of the parameter
number minval
the minimum value of this parameter
number maxval
the maximum value of this parameter

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramindex
the parameter, whose value you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-parameter-states you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetParamEx

Lua: number curval, number minval, number maxval, number midval = ultraschall.InputFX_GetParamEx(integer fxindex, integer paramindex, optional integer tracknumber)

returns the current, maximum, minimum and mid-value of a parameter of a monitoring-fx.

returns nil in case of an error

Returnvalues:
number curval
the current value of the parameter
number minval
the minimum value of this parameter
number maxval
the maximum value of this parameter
number midval
the mid-value of this parameter

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramindex
the parameter, whose value you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-param-states you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetParamName

Lua: boolean retval, string paramname = ultraschall.InputFX_GetParamName(integer fxindex, integer paramindex, optional integer tracknumber)

returns the name of a parameter of a monitoring-fx.

returns false in case of an error

Returnvalues:
boolean retval
true, name can be returned; false, name cannot be returned
string paramname
the name of the parameter

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramindex
the parameter, whose name you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-parameter-name you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetParamNormalized

Lua: integer normalized_value = ultraschall.InputFX_GetParamNormalized(integer fxindex, integer paramindex, optional integer tracknumber)

returns the value of a parameter of a monitoring-fx in a normalized state.

returns nil in case of an error

Returnvalues:
integer normalized_value
the normalized version of the current value

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramindex
the parameter, whose normalized value you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-param-normalized-state you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetParameterStepSizes

Lua: boolean retval, number step, number smallstep, number largestep, boolean istoggle = ultraschall.InputFX_GetParameterStepSizes(integer fxindex, integer paramindex, optional integer tracknumber)

returns the stepsizes of a parameter of a monitoring-fx.

Commonly used for JSFX and VideoProcessor.

returns false in case of an error

Returnvalues:
boolean retval
true, stepsize is available; false; stepsize is not available; nil, in case of an error
number step
the stepsize of this parameter
number smallstep
the stepsize of a small step of this parameter
number largestep
the stepsize of a large step of this parameter
boolean istoggle
true, this parameter is a toggle parameter; false, this parameter is not a togle parameter

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer paramindex
the parameter, whose values you want to retrieve; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-parameter-stepsizes you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_GetPinMappings

Lua: integer pinmappings_Lo32Bit, integer pinmappings_Hi32Bit = ultraschall.InputFX_GetPinMappings(integer fxindex, integer isoutput, integer pin, optional integer tracknumber)

returns the pinmappings as bitfield of a parameter of a monitoring-fx.

returns nil in case of an error

Returnvalues:
integer pinmappings_Lo32Bit
a bitmask for the first 32 connectors, where each bit represents, if this pin is connected(1) or not(0)
integer pinmappings_Hi32Bit
a bitmask for the second 32 connectors, where each bit represents, if this pin is connected(1) or not(0)

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer isoutput
0, for querying input pins; 1, for querying output pins
integer pin
the pin requested, like 0(left), 1(right), etc.
optional integer tracknumber
the tracknumber, whose inputFX-pinmappings you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetPreset

Lua: boolean retval, string preset = ultraschall.InputFX_GetPreset(integer fxindex, optional integer tracknumber)

returns the currently selected preset of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, fx exists; false, fx does not exist
string preset
the name of the currently selected preset; "", if no preset is selected

Parameters:
integer fxindex
the index of the monitoring-fx, whose currently selected presetname-state you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-preset you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetPresetIndex

Lua: integer selected_preset, integer number_of_presets = ultraschall.InputFX_GetPresetIndex(integer fxindex, optional integer tracknumber)

returns the index of the currently selected preset of a monitoring-fx as well as the number of available presets

returns -1 in case of an error

Returnvalues:
integer selected_preset
the index of the currently selected preset; 0, if no preset is selected
integer number_of_presets
the number of presets available    

Parameters:
integer fxindex
the index of the monitoring-fx, whose currently selected preset-index you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-preset you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_GetUserPresetFilename

Lua: string preset_filename = ultraschall.InputFX_GetUserPresetFilename(integer fxindex, optional integer tracknumber)

returns the filename of the presetfile, into which the preset's-settings are stored

returns nil in case of an error

Returnvalues:
string preset_filename
the filename of the preset-file; nil, of not existing

Parameters:
integer fxindex
the index of the monitoring-fx, whose preset's-filename you want to query; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-preset-filename you want to get; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_MoveFX

Lua: boolean retval = ultraschall.InputFX_MoveFX(integer old_fxindex, integer new_fxindex, optional integer tracknumber_source, optional integer tracknumber_target)

Moves a monitoring-fx from an old to a new position

returns false in case of an error

Returnvalues:
boolean retval
true, moving was successful; false, moving was unsuccessful

Parameters:
integer old_fxindex
the index of the input-fx to be moved; 1-based
integer new_fxindex
the new position of the input-fx; 1-based
optional integer tracknumber_source
the tracknumber of the track, from whose inputFX you want to move the fx; 1-based; nil, master-track
optional integer tracknumber_target
the tracknumber of the track, to which you want to move the inputFX; 1-based; nil, master-track    


^ Reaper version 6.05 Ultraschall version 4.2InputFX_MoveFXFromTakeFX

Lua: integer dest_fx = ultraschall.InputFX_MoveFXFromTakeFX(MediaItem_Take take, integer src_fx, integer dest_fx, optional integer dest_tracknumber)

moves a takeFX to monitoringFX

returns -1 in case of an error

Returnvalues:
integer dest_fx
the index of the inserted FX, just in case it differs; 1-based

Parameters:
MediaItem_Take take
the take, from which you want to move the takeFX
integer src_fx
the index takeFX that shall be movd; 1-based
integer dest_fx
the index, at which you want to insert the fx into the monitoring FXChain; 1-based
optional integer dest_tracknumber
the tracknumber, to which you want to move a new inputFX; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_MoveFXFromTrackFX

Lua: integer retval = ultraschall.InputFX_MoveFXFromTrackFX(MediaTrack track, integer old_fxindex, integer new_fxindex, optional integer tracknumberInputFX)

Moves a trackfx to monitoring-fx at a certain position

returns -1 in case of an error

Returnvalues:
integer retval
the index of the inserted fx(in case of being different from new_fxindex); -1, in case of an error

Parameters:
MediaTrack track
the track from which you want to copy a trackfx to monitoring-fx
integer old_fxindex
the index of the monitoring-fx to be moved; 1-based
integer new_fxindex
the position of the newly inserted input-fx; 1-based
optional integer tracknumberInputFX
the tracknumber, to whose inputFX the fx shall be moved to; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_MoveFXToTakeFX

Lua: integer dest_fx = ultraschall.InputFX_MoveFXToTakeFX(integer src_fx, MediaItem_Take take, integer dest_fx)

moves a monitoring-FX to a takeFX

returns -1 in case of an error

Returnvalues:
integer dest_fx
the index of the inserted FX, just in case it differs; 1-based

Parameters:
integer src_fx
the index inputFX that shall be moved; 1-based
MediaItem_Take take
the take, into which you want to insert the fx as takeFX
integer dest_fx
the index, at which you want to insert the fx; 1-based
optional integer src_tracknumber
the tracknumber, whose inputFX you want to move; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_MoveFXToTrackFX

Lua: integer retval = ultraschall.InputFX_MoveFXToTrackFX(integer old_fxindex, MediaTrack track, integer new_fxindex)

moves a monitoring-fx and inserts it as trackfx at a certain position

returns -1 in case of an error

Returnvalues:
integer retval
the index of the inserted fx(in case of being different from new_fxindex); -1, in case of an error

Parameters:
integer old_fxindex
the index of the monitoring-fx to be moved; 1-based
MediaTrack track
the track into which you want to insert the trackFX
integer new_fxindex
the position of the newly inserted track-fx; 1-based


^ Reaper version 6.05 Ultraschall version 4.2InputFX_NavigatePresets

Lua: boolean retval = ultraschall.InputFX_NavigatePresets(integer fxindex, integer presetmove, optional integer tracknumber)

switches the preset of a monitoring-fx through, relative from its current preset-index.
You can move by multiple presets, so 1 moves one further, 2 moves 2 further, -3 moves 3 backwards.

If you hit the first/last preset, it will go back to the last/first preset respectively.

returns false in case of an error

Returnvalues:
boolean retval
true, altering was successful; false, altering was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx, whose preset you want to switch through; 1-based
integer presetmove
positive, move forward by value of presetmove; negative, move backwards by value of presetmove
optional integer tracknumber
the tracknumber, whose inputFX-preset you want to navigate; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_QueryFirstFXIndex

Lua: integer fxindex = ultraschall.InputFX_QueryFirstFXIndex(string fxname, optional integer tracknumber)

Queries the fx-index of the first inputfx with fxname

returns -1 in case of an error

Returnvalues:
integer fxindex
the index of the queried fx; 1-based; -1, in case of an error

Parameters:
string fxname
the name of the fx to be queried
optional integer tracknumber
the tracknumber, to whose inputFX the fx shall be added; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetEQBandEnabled

Lua: boolean retval = ultraschall.InputFX_SetEQBandEnabled(integer fxindex, integer bandtype, integer bandidx, boolean enable, optional integer tracknumber)

Enable or disable a ReaEQ band of a monitoring-fx.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer bandtype
the bandtype of the band to change;
0, lhipass
1, loshelf
2, band
3, notch
4, hishelf
5, lopass
integer bandidx
0, first band matching bandtype; 1, 2nd band matching bandtype, etc.
boolean enable
true, enable band; false, disable band
optional integer tracknumber
the tracknumber, whose inputFX-eq-band-enabled-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetEQParam

Lua: boolean retval = ultraschall.InputFX_SetEQParam(integer fxindex, integer bandtype, integer bandidx, integer paramtype, number val, boolean isnorm)

Sets an EQ-parameter of a ReaEQ-instance in monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer bandtype
the bandtype of the band to change;
0, lhipass
1, loshelf
2, band
3, notch
4, hishelf
5, lopass
integer bandidx
0, first band matching bandtype; 1, 2nd band matching bandtype, etc.
integer paramtype
0, freq; 1, gain; 2, Q
number val
the new value for the paramtype of a bandidx
boolean isnorm
true, value is normalized; false, value is not normalized
optional integer tracknumber
the tracknumber, whose inputFX-eq-param-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_SetEnabled

Lua: boolean retval = ultraschall.InputFX_SetEnabled(integer fxindex, boolean enabled, optional integer tracknumber)

Sets a monitoring-fx to enabled.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx which you want to disable/enable; 1-based
boolean enabled
true, enable the monitoring-fx; false, disable the monitoring-fx
optional integer tracknumber
the tracknumber, whose inputFX-enabled-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetFXChain

Lua: boolean retval = ultraschall.InputFX_SetFXChain(string FXStateChunk, boolean replacefx, optional integer tracknumber)

Inserts an FXStateChunk into the monitoring-fx-chain. Allows replacing it as well.

This could potentially create hiccups in the audio-engine of Reaper.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
string FXStateChunk
the FXStateChunk that shall be set as monitoring fx-chain
boolean replacefx
true, replace the current monitoring-fx-chain with the new one; false, only insert the new fx at the end of the FXChain
optional integer tracknumber
the track, whose inputFX-chain you want to set; 0 or nil, global monitoring fx


^ Reaper version 6.05 Ultraschall version 4.2InputFX_SetOffline

Lua: boolean retval = ultraschall.InputFX_SetOffline(integer fxindex, boolean offline, optional integer tracknumber)

Sets a monitoring-fx to online/offline.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx which you want to set offline/online; 1-based
boolean offline
true, set the monitoring-fx offline; false, set the monitoring-fx online
optional integer tracknumber
the tracknumber, whose inputFX-offline-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_SetOpen

Lua: boolean retval = ultraschall.InputFX_SetOpen(integer fxindex, boolean open, optional integer tracknumber)

Sets a monitoring-fx visible of invisible

If you change the index while open=true, the visible fx will change to the new one.

Setting open=false closes the monitoring-fx-chain, open=true will open the monitoring-fx-chain if not visible yet.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx which you want to visible/invisible; 1-based
boolean open
true, set the monitoring-fx visible; false, set the monitoring-fx invisible
optional integer tracknumber
the tracknumber, whose inputFX-visibility-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetParam

Lua: boolean retval = ultraschall.InputFX_SetParam(integer fxindex, index parameterindex, number val, optional integer tracknumber)

Sets a new value of a parameter of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
index parameterindex
the index of the parameter to be set; 1-based
number val
the new value to set
optional integer tracknumber
the tracknumber, whose inputFX-param-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetParamNormalized

Lua: boolean retval = ultraschall.InputFX_SetParamNormalized(integer fxindex, index parameterindex, number val, optional integer tracknumber)

Sets a new value as normalized of a parameter of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
index parameterindex
the index of the parameter to be set; 1-based
number val
the new value to set
optional integer tracknumber
the tracknumber, whose inputFX-parameter you want to set normalized; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.02 Ultraschall version 4.2InputFX_SetPinMappings

Lua: boolean retval = ultraschall.InputFX_SetPinMappings(integer fxindex, integer isoutput, integer pin, integer low32bits, integer hi32bits, optional integer tracknumber)

sets the pinmappings as bitfield of a parameter of a monitoring-fx.

returns false in case of an error or if unsupported (not all types of plug-ins support this capability)

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx; 1-based
integer isoutput
0, for querying input pins; 1, for querying output pins
integer pin
the pin requested, like 0(left), 1(right), etc.
integer pinmappings_Lo32Bit
a bitmask for the first 32 connectors, where each bit represents, if this pin is connected(1) or not(0)
integer pinmappings_Hi32Bit
a bitmask for the second 32 connectors, where each bit represents, if this pin is connected(1) or not(0)
optional integer tracknumber
the tracknumber, whose inputFX-pinmappings you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_SetPreset

Lua: boolean retval = ultraschall.InputFX_SetPreset(integer fxindex, string presetname)

Sets the preset of a monitoring-fx by presetname.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx of which you want to set the preset; 1-based
string presetname
the name of the preset, that you want to select
optional integer tracknumber
the tracknumber, whose inputFX-preset you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_SetPresetByIndex

Lua: boolean retval = ultraschall.InputFX_SetPresetByIndex(integer fxindex, integer presetindex, optional integer tracknumber)

Sets the preset of a monitoring-fx by preset-index.

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx which you want to set the preset; 1-based
integer presetindex
the index of the preset, that you want to select; 0, for default; -1, for no preset; 1-based
optional integer tracknumber
the tracknumber, whose inputFX-preset you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 6.05 Ultraschall version 4.2InputFX_Show

Lua: boolean retval = ultraschall.InputFX_Show(integer fxindex, integer showflag, optional integer tracknumber)

Sets visibility and floating-state of a monitoring-fx

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
integer fxindex
the index of the monitoring-fx which you want to set the preset; 1-based
integer showflag
0, for hidechain
1, for show chain(index valid)
2, for hide floating window (index valid)
3, for show floating window (index valid)
optional integer tracknumber
the tracknumber, whose inputFX-shown-state you want to set; 0 or nil, global monitoring fx; 1 and higher, track 1 and higher


^ Reaper version 5.979 Ultraschall version 4.1AddParmAlias_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx, string parmalias)

Adds a new Parm-Alias-entry to an FX-plugin from an FXStateChunk.

It's the PARMALIAS-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Alias-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Alias-entry; beginning with 1
integer parmidx
the parameter, whose alias you want to add
string parmalias
the new aliasname of the parameter


^ Reaper version 5.979 Ultraschall version 4.00CountParmAlias_FXStateChunk

Lua: integer count = ultraschall.CountParmAlias_FXStateChunk(string FXStateChunk, integer fxid)

Counts already existing Parm-Alias-entries of an FX-plugin from an FXStateChunk.

It's the PARMALIAS-entry

returns -1 in case of an error

Returnvalues:
integer count
the number of ParmAliases found

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to count a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-count-Parm-Learn-entry; beginning with 1


^ Reaper version 5.979 Ultraschall version 4.1DeleteParmAlias2_FXStateChunk

Lua: boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmAlias2_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx)

Deletes a ParmAlias-entry from an FXStateChunk.

It's the PARMALIAS-entry

Unlike DeleteParmAlias_FXStateChunk, this indexes aliasnames by parameter-index directly, not by number of already existing aliasnames.
When in doubt, use this one.

returns false in case of an error

Returnvalues:
boolean retval
true, if deletion was successful; false, if the function couldn't delete anything
string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, which you want to delete a ParmAlias from
integer fxid
the id of the fx, which holds the to-delete-ParmAlias-entry; beginning with 1
integer parmidx
the id of the parameter, whose parmalias you want to delete; beginning with 1


^ Reaper version 5.979 Ultraschall version 4.00DeleteParmAlias_FXStateChunk

Lua: boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Deletes a ParmAlias-entry from an FXStateChunk.

It's the PARMALIAS-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if deletion was successful; false, if the function couldn't delete anything
string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, which you want to delete a ParmAlias from
integer fxid
the id of the fx, which holds the to-delete-ParmAlias-entry; beginning with 1
integer id
the id of the ParmAlias-entry to delete; beginning with 1


^ Reaper version 5.979 Ultraschall version 4.1GetAllParmAliasNames_FXStateChunk

Lua: integer count_aliasnames, array parameteridx, array parameter_aliasnames = ultraschall.GetAllParmAliasNames_FXStateChunk(string FXStateChunk, integer fxid)

Returns all aliasnames of a specific fx within an FXStateChunk

returns -1 in case of an error

Returnvalues:
integer count_aliasnames
the number of parameter-aliases found for this fx
array parameteridx
an array, which holds all parameter-index-numbers of all fx with parameter-aliasnames
array parameter_aliasnames
an array with all parameter-aliasnames found

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to get all Parm-Aliases
integer fxid
the id of the fx, whose Parm-Aliases you want to get


^ Reaper version 5.975 Ultraschall version 4.1GetParmAlias2_FXStateChunk

Lua: integer parm_idx, string parm_aliasname = ultraschall.GetParmAlias2_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Returns a parameter-alias-setting of a specific parameter from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

Parameter-aliases are only stored for MediaTracks.

It is the PARMALIAS-entry

Returns nil in case of an error or if no such aliasname has been found

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parm_aliasname
the alias-name of the parameter

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmAlias-settings
integer fxid
the fx, of which you want to get the parameter-alias-settings
integer parmidx
the id of the parameter whose aliasname you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.00GetParmAlias_FXStateChunk

Lua: integer parm_idx, string parm_aliasname = ultraschall.GetParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Returns a parameter-alias-setting from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

Parameter-aliases are only stored for MediaTracks.

It is the PARMALIAS-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parm_aliasname
the alias-name of the parameter

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmAlias-settings
integer fxid
the fx, of which you want to get the parameter-alias-settings
integer id
the id of the ParmAlias-settings you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.1GetParmAlias_MediaTrack

Lua: integer parm_idx, string parm_aliasname = ultraschall.GetParmAlias_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Returns a parameter-aliasname-setting from a MediaTrack

It is the PARMALIAS-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parm_aliasname
the alias-name of the parameter

Parameters:
MediaTrack MediaTrack
the MediaTrack, whose ParmAlias-setting you want to get
integer fxid
the fx, of which you want to get the parameter-alias-settings
integer id
the id of the ParmAlias-settings you want to have, starting with 1 for the first


^ Reaper version 5.979 Ultraschall version 4.1SetParmAlias2_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmAlias2_FXStateChunk(string FXStateChunk, integer fxid, integer id, string parmalias)

Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.

Unlike SetParmAlias_FXStateChunk, the parameter id counts by parameter-order, not existing aliasnames. If a parameter has no aliasname yet, it will return false.

It's the PARMALIAS-entry



returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Alias-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Alias-entry; beginning with 1
integer id
the index of the parameter, whose Parm-Alias-entry you want to to set; beginning with 1
string parmalias
the new aliasname of the parameter


^ Reaper version 5.979 Ultraschall version 4.1SetParmAlias_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id, string parmalias)

Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.

It's the PARMALIAS-entry

The parameter id counts with the first aliasname found in the FXStateChunk for this fx, regardless, if the first found aliasname is for parameter 1 or 23, etc. If you want to adress it by parameter-index, use SetParmAlias2_FXStateChunk instead.

returns false in case of an error


Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Alias-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Alias-entry; beginning with 1
integer id
the id of the Parm-Alias-entry to set; beginning with 1
string parmalias
the new aliasname of the parameter


^ Reaper version 5.979 Ultraschall version 4.00AddParmLFOLearn_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message)

Adds a new Parm-LFOLearn-entry to an FX-plugin from an FXStateChunk.

It's the LFOLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1
integer parmidx
the parameter, whose alias you want to add
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give!
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...        
            
       CC Mode-dropdownlist:
          set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
           &65536 &131072 &262144
              0       0       0,      Absolute
              1       0       0,      Relative 1(127=-1, 1=+1)
              0       1       0,      Relative 2(63=-1, 65=+1)
              1       1       0,      Relative 3(65=-1, 1=+1)
              0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLFOLearn, only when midi_note is set to 0!


^ Reaper version 5.979 Ultraschall version 4.00CountParmLFOLearn_FXStateChunk

Lua: integer count = ultraschall.CountParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid)

Counts already existing Parm-LFOLearn-entries of an FX-plugin from an FXStateChunk.

It's the LFOLEARN-entry

returns -1 in case of an error

Returnvalues:
integer count
the number of LFOLearn-entries found

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to count a Parm-LFOLearn-entry
integer fxid
the id of the fx, which holds the to-count-Parm-LFOLearn-entry; beginning with 1


^ Reaper version 5.979 Ultraschall version 4.00DeleteParmLFOLearn_FXStateChunk

Lua: boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Deletes a ParmLFO-Learn-entry from an FXStateChunk.

It's the LFOLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if deletion was successful; false, if the function couldn't delete anything
string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, which you want to delete a ParmLFO-Learn-entry from
integer fxid
the id of the fx, which holds the to-delete-ParmLFO-Learn-entry; beginning with 1
integer id
the id of the ParmLFO-Learn-entry to delete; beginning with 1


^ Reaper version 5.975 Ultraschall version 4.00GetParmLFOLearn_FXStateChunk

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Returns a parameter-lfo-learn-setting from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

It is the LFOLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...        
            
       CC Mode-dropdownlist:
          set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
           &65536 &131072 &262144
              0       0       0,      Absolute
              1       0       0,      Relative 1(127=-1, 1=+1)
              0       1       0,      Relative 2(63=-1, 65=+1)
              1       1       0,      Relative 3(65=-1, 1=+1)
              0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLFOLearn

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmLFOLearn-settings
integer fxid
the fx, of which you want to get the parameter-lfo-learn-settings
integer id
the id of the ParmLFOLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.00GetParmLFOLearn_MediaItem

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_MediaItem(MediaItem MediaItem, integer fxid, integer id)

Returns a parameter-lfo-learn-setting from a MediaItem

It is the LFOLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...        
            
       CC Mode-dropdownlist:
          set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
           &65536 &131072 &262144
              0       0       0,      Absolute
              1       0       0,      Relative 1(127=-1, 1=+1)
              0       1       0,      Relative 2(63=-1, 65=+1)
              1       1       0,      Relative 3(65=-1, 1=+1)
              0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLFOLearn

Parameters:
MediaItem MediaItem
the MediaItem, whose ParmLFOLearn-setting you want to get
integer fxid
the fx, of which you want to get the parameter-lfo-learn-settings
integer id
the id of the ParmLFOLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.00GetParmLFOLearn_MediaTrack

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Returns a parameter-lfo-learn-setting from a MediaTrack

It is the LFOLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...        
            
       CC Mode-dropdownlist:
          set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
           &65536 &131072 &262144
              0       0       0,      Absolute
              1       0       0,      Relative 1(127=-1, 1=+1)
              0       1       0,      Relative 2(63=-1, 65=+1)
              1       1       0,      Relative 3(65=-1, 1=+1)
              0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLFOLearn

Parameters:
MediaTrack MediaTrack
the MediaTrack, whose ParmLFOLearn-setting you want to get
integer fxid
the fx, of which you want to get the parameter-lfo-learn-settings
integer id
the id of the ParmLFOLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.979 Ultraschall version 4.00SetParmLFOLearn_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id, integer midi_note, integer checkboxflags, optional string osc_message)

Sets an already existing ParmLFO-Learn-entry of an FX-plugin from an FXStateChunk.

It's the LFOLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLFO)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a ParmLFO-Learn-entry
integer fxid
the id of the fx, which holds the to-set-ParmLFO-Learn-entry; beginning with 1
integer id
the id of the ParmLFO-Learn-entry to set; beginning with 1
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...        
            
       CC Mode-dropdownlist:
          set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
           &65536 &131072 &262144
              0       0       0,      Absolute
              1       0       0,      Relative 1(127=-1, 1=+1)
              0       1       0,      Relative 2(63=-1, 65=+1)
              1       1       0,      Relative 3(65=-1, 1=+1)
              0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLFOLearn, only when midi_note is set to 0!


^ Reaper version 5.979 Ultraschall version 4.00AddParmLearn_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message)

Adds a new Parm-Learn-entry to an FX-plugin from an FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1
integer parmidx
the parameter, whose Parameter Learn you want to add
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give, otherwise just pass ""
integer midi_note
an integer representation of the MIDI-note, which is set as command; 0, in case of an OSC-message
examples:
         0,   OSC is used
         176, MIDI Chan 1 CC 0
         ...
         432, MIDI Chan 1 CC 1
         ...
         9360, MIDI Chan 1 Note 36
         9616, MIDI Chan 1 Note 37
         9872, MIDI Chan 1 Note 38
           ...
          
     CC Mode-dropdownlist:
        set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
         &65536 &131072 &262144
            0       0       0,      Absolute
            1       0       0,      Relative 1(127=-1, 1=+1)
            0       1       0,      Relative 2(63=-1, 65=+1)
            1       1       0,      Relative 3(65=-1, 1=+1)
            0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 6.32 Ultraschall version 4.2AddParmLearn_FXStateChunk2

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer input_mode, integer channel, integer cc_note, integer cc_mode, integer checkboxflags, optional string osc_message)

Adds a new Parm-Learn-entry to an FX-plugin from an FXStateChunk.
Allows setting some values more detailed, unlike AddParmLearn_FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1
integer parmidx
the parameter, whose Parameter Learn you want to add; 0-based
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give, otherwise just pass ""
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 6.32 Ultraschall version 4.2AddParmLearn_FXStateChunk2

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer input_mode, integer channel, integer cc_note, integer cc_mode, integer checkboxflags, optional string osc_message)

Adds a new Parm-Learn-entry to an FX-plugin from an FXStateChunk.
Allows setting some values more detailed, unlike AddParmLearn_FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1
integer parmidx
the parameter, whose Parameter Learn you want to add; 0-based
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give, otherwise just pass ""
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 5.979 Ultraschall version 4.1CountParmLearn_FXStateChunk

Lua: integer count = ultraschall.CountParmLearn_FXStateChunk(string FXStateChunk, integer fxid)

Counts already existing Parm-Learn-entries of an FX-plugin from an FXStateChunk.

It's the PARMLEARN-entry

returns -1 in case of an error

Returnvalues:
integer count
the number of ParmLearn-entries found

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to count a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-count-Parm-Learn-entry; beginning with 1


^ Reaper version 6.02 Ultraschall version 4.2DeleteParmLearn2_FXStateChunk

Lua: boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmLearn2_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx)

Deletes a ParmLearn-entry from an FXStateChunk, by parameter index.

Unlike DeleteParmLearn_FXStateChunk, this indexes the parameters not the already existing parmlearns.

returns false in case of an error


Returnvalues:
boolean retval
true, if deletion was successful; false, if the function couldn't delete anything
string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, which you want to delete a ParmLearn from
integer fxid
the id of the fx, which holds the to-delete-ParmLearn-entry; beginning with 1
integer parmidx
the index of the parameter, whose parmlearn you want to delete; beginning with 1


^ Reaper version 5.979 Ultraschall version 4.00DeleteParmLearn_FXStateChunk

Lua: boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Deletes a ParmLearn-entry from an FXStateChunk.

Unlike DeleteParmLearn2_FXStateChunk, this indexes by the already existing parmlearns and not by parameters.

returns false in case of an error


Returnvalues:
boolean retval
true, if deletion was successful; false, if the function couldn't delete anything
string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, which you want to delete a ParmLearn from
integer fxid
the id of the fx, which holds the to-delete-ParmLearn-entry; beginning with 1
integer id
the id of the ParmLearn-entry to delete; beginning with 1


^ Reaper version 5.975 Ultraschall version 4.00GetParmLearn_FXStateChunk

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Returns a parameter-learn-setting from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

It is the PARMLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
  being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...
        
  CC Mode-dropdownlist:
     set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
      &65536 &131072 &262144
         0       0       0,      Absolute
         1       0       0,      Relative 1(127=-1, 1=+1)
         0       1       0,      Relative 2(63=-1, 65=+1)
         1       1       0,      Relative 3(65=-1, 1=+1)
         0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmLearn-settings
integer fxid
the fx, of which you want to get the parameter-learn-settings
integer id
the id of the ParmLearn-settings you want to have, starting with 1 for the first


^ Reaper version 6.32 Ultraschall version 4.2GetParmLearn_FXStateChunk2

Lua: integer parm_idx, string parmname, integer input_mode, integer channel, integer cc_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer id)

Returns a parameter-learn-setting from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

Returns some values more detailed, unlike GetParmLearn_FXStateChunk.

It is the PARMLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmLearn-settings
integer fxid
the fx, of which you want to get the parameter-learn-settings
integer id
the id of the ParmLearn-settings you want to have, starting with 1 for the first


^ Reaper version 6.32 Ultraschall version 4.2GetParmLearn_FXStateChunk2

Lua: integer parm_idx, string parmname, integer input_mode, integer channel, integer cc_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer id)

Returns a parameter-learn-setting from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

Returns some values more detailed, unlike GetParmLearn_FXStateChunk.

It is the PARMLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the ParmLearn-settings
integer fxid
the fx, of which you want to get the parameter-learn-settings
integer id
the id of the ParmLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.00GetParmLearn_MediaItem

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_MediaItem(MediaItem MediaItem, integer fxid, integer id)

Returns a parameter-learn-setting from a MediaItem

It is the PARMLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
  being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...
        
  CC Mode-dropdownlist:
     set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
      &65536 &131072 &262144
         0       0       0,      Absolute
         1       0       0,      Relative 1(127=-1, 1=+1)
         0       1       0,      Relative 2(63=-1, 65=+1)
         1       1       0,      Relative 3(65=-1, 1=+1)
         0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn

Parameters:
MediaItem MediaItem
the MediaItem, whose ParmLearn-setting you want to get
integer fxid
the fx, of which you want to get the parameter-learn-settings
integer id
the id of the ParmLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.975 Ultraschall version 4.00GetParmLearn_MediaTrack

Lua: integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Returns a parameter-learn-setting from a MediaTrack

It is the PARMLEARN-entry

Returns nil in case of an error

Returnvalues:
integer parm_idx
the idx of the parameter; order is exactly like the order in the contextmenu of Parameter List -> Learn
string parmname
the name of the parameter, though usually only wet or bypass
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
  being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...
        
  CC Mode-dropdownlist:
     set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
      &65536 &131072 &262144
         0       0       0,      Absolute
         1       0       0,      Relative 1(127=-1, 1=+1)
         0       1       0,      Relative 2(63=-1, 65=+1)
         1       1       0,      Relative 3(65=-1, 1=+1)
         0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
0, no checkboxes
1, enable only when track or item is selected
2, Soft takeover (absolute mode only)
3, Soft takeover (absolute mode only)+enable only when track or item is selected
4, enable only when effect configuration is focused
20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn

Parameters:
MediaTrack MediaTrack
the MediaTrack, whose ParmLearn-setting you want to get
integer fxid
the fx, of which you want to get the parameter-learn-settings
integer id
the id of the ParmLearn-settings you want to have, starting with 1 for the first


^ Reaper version 5.979 Ultraschall version 4.00SetParmLearn_FXStateChunk

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id, integer midi_note, integer checkboxflags, optional string osc_message)

Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1
integer id
the id of the Parm-Learn-entry to set; beginning with 1
integer midi_note
the midinote, that is assigned to this; this is a multibyte value, with the first byte
  being the MIDI-mode, and the second byte the MIDI/CC-note
      0,   OSC is used
      176, MIDI Chan 1 CC 0     (Byte1=176, Byte2=0)
      ...
      432, MIDI Chan 1 CC 1     (Byte1=176, Byte2=1)
      ...
      144,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=0)
      400,  MIDI Chan 1 Note 1  (Byte1=144, Byte2=1)
      ...
      9360, MIDI Chan 1 Note 36 (Byte1=144, Byte2=36)
      9616, MIDI Chan 1 Note 37 (Byte1=144, Byte2=37)
      9872, MIDI Chan 1 Note 38 (Byte1=144, Byte2=38)
        ...
        
  CC Mode-dropdownlist:
     set the following flags to their specific values (0=0, 1=the value beginning &, like &65536 or &131072 or &262144)
      &65536 &131072 &262144
         0       0       0,      Absolute
         1       0       0,      Relative 1(127=-1, 1=+1)
         0       1       0,      Relative 2(63=-1, 65=+1)
         1       1       0,      Relative 3(65=-1, 1=+1)
         0       0       1,      Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 6.32 Ultraschall version 4.2SetParmLearn_FXStateChunk2

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer input_mode, integer channel, integer cc_note, integer cc_mode, integer checkboxflags, optional string osc_message)

Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.
Allows setting some values more detailed, unlike SetParmLearn_FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1    
integer parmidx
the parameter, whose Parameter Learn you want to add; 0-based
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give, otherwise just pass ""
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 6.32 Ultraschall version 4.2SetParmLearn_FXStateChunk2

Lua: boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLearn_FXStateChunk2(string FXStateChunk, integer fxid, integer parmidx, string parmname, integer input_mode, integer channel, integer cc_note, integer cc_mode, integer checkboxflags, optional string osc_message)

Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.
Allows setting some values more detailed, unlike SetParmLearn_FXStateChunk.

It's the PARMLEARN-entry

returns false in case of an error

Returnvalues:
boolean retval
true, if setting new values was successful; false, if setting was unsuccessful(e.g. no such ParmLearn)
optional string alteredFXStateChunk
the altered FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk, in which you want to set a Parm-Learn-entry
integer fxid
the id of the fx, which holds the to-set-Parm-Learn-entry; beginning with 1    
integer parmidx
the parameter, whose Parameter Learn you want to add; 0-based
string parmname
the name of the parameter, usually \"\" or \"byp\" for bypass or \"wet\" for wet; when using wet or bypass, these are essential to give, otherwise just pass ""
integer input_mode
the input mode of this ParmLearn-entry
0, OSC
1, MIDI Note
2, MIDI CC
3, MIDI PC
4, MIDI Pitch
integer channel
the midi-channel used; 1-16
integer cc_note
the midi/cc-note used; 0-127
integer cc_mode
the cc-mode-dropdownlist
0, Absolute
1, Relative 1(127=-1, 1=+1)
2, Relative 2(63=-1, 65=+1)
3, Relative 3(65=-1, 1=+1)
4, Toggle (>0=toggle)
integer checkboxflags
the checkboxes checked in the MIDI/OSC-learn dialog
   0, no checkboxes
   1, enable only when track or item is selected
   2, Soft takeover (absolute mode only)
   3, Soft takeover (absolute mode only)+enable only when track or item is selected
   4, enable only when effect configuration is focused
   20, enable only when effect configuration is visible
optional string osc_message
the osc-message, that triggers the ParmLearn, only when midi_note is set to 0!


^ Reaper version 6.02 Ultraschall version 4.1AddParmMod_ParmModTable

Lua: string FXStateChunk = ultraschall.AddParmMod_ParmModTable(string FXStateChunk, integer fxindex, table ParmModTable)

Takes a ParmModTable and adds with its values a new Parameter Modulation of a specific fx within an FXStateChunk.

The expected table's format is as follows:

ParmModTable["PARAM_NR"]               - the parameter that you want to modulate; 1 for the first, 2 for the second, etc
ParmModTable["PARAM_TYPE"]             - the type of the parameter, usually "", "wet" or "bypass"

ParmModTable["PARAMOD_ENABLE_PARAMETER_MODULATION"] 
                                       - Enable parameter modulation, baseline value(envelope overrides)-checkbox; 
                                          true, checked; false, unchecked
ParmModTable["PARAMOD_BASELINE"]       - Enable parameter modulation, baseline value(envelope overrides)-slider; 
                                            0.000 to 1.000

ParmModTable["AUDIOCONTROL"]           - is the Audio control signal(sidechain)-checkbox checked; true, checked; false, unchecked
                                            Note: if true, this needs all AUDIOCONTROL_-entries to be set
ParmModTable["AUDIOCONTROL_CHAN"]      - the Track audio channel-dropdownlist; When stereo, the first stereo-channel;
                                          nil, if not available
ParmModTable["AUDIOCONTROL_STEREO"]    - 0, just use mono-channels; 1, use the channel AUDIOCONTROL_CHAN plus 
                                            AUDIOCONTROL_CHAN+1; nil, if not available
ParmModTable["AUDIOCONTROL_ATTACK"]    - the Attack-slider of Audio Control Signal; 0-1000 ms; nil, if not available
ParmModTable["AUDIOCONTROL_RELEASE"]   - the Release-slider; 0-1000ms; nil, if not available
ParmModTable["AUDIOCONTROL_MINVOLUME"] - the Min volume-slider; -60dB to 11.9dB; must be smaller than AUDIOCONTROL_MAXVOLUME; 
                                          nil, if not available
ParmModTable["AUDIOCONTROL_MAXVOLUME"] - the Max volume-slider; -59.9dB to 12dB; must be bigger than AUDIOCONTROL_MINVOLUME; 
                                          nil, if not available
ParmModTable["AUDIOCONTROL_STRENGTH"]  - the Strength-slider; 0(0%) to 1000(100%)
ParmModTable["AUDIOCONTROL_DIRECTION"] - the direction-radiobuttons; -1, negative; 0, centered; 1, positive
ParmModTable["X2"]=0.5                 - the audiocontrol signal shaping-x-coordinate
ParmModTable["Y2"]=0.5                 - the audiocontrol signal shaping-y-coordinate    

ParmModTable["LFO"]                    - if the LFO-checkbox checked; true, checked; false, unchecked
                                            Note: if true, this needs all LFO_-entries to be set
ParmModTable["LFO_SHAPE"]              - the LFO Shape-dropdownlist; 
                                            0, sine; 1, square; 2, saw L; 3, saw R; 4, triangle; 5, random
                                            nil, if not available
ParmModTable["LFO_SHAPEOLD"]           - use the old-style of the LFO_SHAPE; 
                                            0, use current style of LFO_SHAPE; 
                                            1, use old style of LFO_SHAPE; 
                                            nil, if not available
ParmModTable["LFO_TEMPOSYNC"]          - the Tempo sync-checkbox; true, checked; false, unchecked
ParmModTable["LFO_SPEED"]              - the LFO Speed-slider; 0(0.0039Hz) to 1(8.0000Hz); nil, if not available
ParmModTable["LFO_STRENGTH"]           - the LFO Strength-slider; 0.000(0.0%) to 1.000(100.0%)
ParmModTable["LFO_PHASE"]              - the LFO Phase-slider; 0.000 to 1.000; nil, if not available
ParmModTable["LFO_DIRECTION"]          - the LFO Direction-radiobuttons; -1, Negative; 0, Centered; 1, Positive
ParmModTable["LFO_PHASERESET"]         - the LFO Phase reset-dropdownlist; 
                                            0, On seek/loop(deterministic output)
                                            1, Free-running(non-deterministic output)
                                            nil, if not available

ParmModTable["MIDIPLINK"]              - true, if any parameter-linking with MIDI-stuff; false, if not
                                            Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
ParmModTable["PARMLINK"]               - the Link from MIDI or FX parameter-checkbox
                                          true, checked; false, unchecked
ParmModTable["PARMLINK_LINKEDPLUGIN"]  - the selected plugin; nil, if not available
                                       - will be ignored, when PARMLINK_LINKEDPLUGIN_RELATIVE is set
                                            -1, nothing selected yet
                                            -100, MIDI-parameter-settings
                                            1 - the first fx-plugin
                                            2 - the second fx-plugin
                                            3 - the third fx-plugin, etc
ParmModTable["PARMLINK_LINKEDPLUGIN_RELATIVE"] - the linked plugin relative to the current one in the FXChain
                                               - 0, use parameter of the current fx-plugin
                                               - negative, use parameter of a plugin above of the current plugin(-1, the one above; -2, two above, etc)
                                               - positive, use parameter of a plugin below the current plugin(1, the one below; 2, two below, etc)
                                               - nil, use only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX)
ParmModTable["PARMLINK_LINKEDPARMIDX"] - the id of the linked parameter; -1, if none is linked yet; nil, if not available
                                            When MIDI, this is irrelevant.
                                            When FX-parameter:
                                              0 to n; 0 for the first; 1, for the second, etc

ParmModTable["PARMLINK_OFFSET"]        - the Offset-slider; -1.00(-100%) to 1.00(+100%); nil, if not available
ParmModTable["PARMLINK_SCALE"]         - the Scale-slider; -1.00(-100%) to 1.00(+100%); nil, if not available

ParmModTable["MIDIPLINK"]              - true, if any parameter-linking with MIDI-stuff; false, if not
                                            Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
ParmModTable["MIDIPLINK_BUS"]          - the MIDI-bus selected in the button-menu; 
                                            0 to 15 for bus 1 to 16; 
                                            nil, if not available
ParmModTable["MIDIPLINK_CHANNEL"]      - the MIDI-channel selected in the button-menu; 
                                            0, omni; 1 to 16 for channel 1 to 16; 
                                            nil, if not available
ParmModTable["MIDIPLINK_MIDICATEGORY"] - the MIDI_Category selected in the button-menu; nil, if not available
                                            144, MIDI note
                                            160, Aftertouch
                                            176, CC 14Bit and CC
                                            192, Program Change
                                            208, Channel Pressure
                                            224, Pitch
ParmModTable["MIDIPLINK_MIDINOTE"]     - the MIDI-note selected in the button-menu; nil, if not available
                                          When MIDI note:
                                               0(C-2) to 127(G8)
                                          When Aftertouch:
                                               0(C-2) to 127(G8)
                                          When CC14 Bit:
                                               128 to 159; see dropdownlist for the commands(the order of the list 
                                               is the same as this numbering)
                                          When CC:
                                               0 to 119; see dropdownlist for the commands(the order of the list 
                                               is the same as this numbering)
                                          When Program Change:
                                               0
                                          When Channel Pressure:
                                               0
                                          When Pitch:
                                               0
ParmModTable["WINDOW_ALTERED"]         - false, if the windowposition hasn't been altered yet; true, if the window has been altered
                                            Note: if true, this needs all WINDOW_-entries to be set
ParmModTable["WINDOW_ALTEREDOPEN"]     - if the position of the ParmMod-window is altered and currently open; 
                                                    nil, unchanged; 0, unopened; 1, open
ParmModTable["WINDOW_XPOS"]            - the x-position of the altered ParmMod-window in pixels; nil, default position
ParmModTable["WINDOW_YPOS"]            - the y-position of the altered ParmMod-window in pixels; nil, default position
ParmModTable["WINDOW_RIGHT"]           - the right-position of the altered ParmMod-window in pixels; 
                                            nil, default position; only readable
ParmModTable["WINDOW_BOTTOM"]          - the bottom-position of the altered ParmMod-window in pixels; 
                                            nil, default position; only readable

This function does not check, if the values are within valid value-ranges, only if the datatypes are valid.

returns nil in case of an error


Returnvalues:
string FXStateChunk
the altered FXStateChunk, where the ParameterModulation shall be added

Parameters:
string FXStateChunk
an FXStateChunk, of which you want to add the values of a specific parameter-modulation
integer fxindex
the index of the fx, of which you want to add specific parameter-modulation-values
table ParmModTable
the table which holds all parameter-modulation-values to be added


^ Reaper version 6.10 Ultraschall version 4.2CountParmModFromFXStateChunk

Lua: integer number_of_parmmodulations = ultraschall.CountParmModFromFXStateChunk(string FXStateChunk, integer fxindex)

returns the number of parameter-modulations available for a specific fx in an FXStateChunk

returns -1 in case of an error

Returnvalues:
integer number_of_parmmodulations
the number of parameter-modulations available for this fx within this FXStateChunk

Parameters:
string FXStateChunk
the FXStateChunk from which you want to count the parameter-modulations available for a specific fx
integer fxindex
the index of the fx, whose number of parameter-modulations you want to know


^ Reaper version 6.10 Ultraschall version 4.1CreateDefaultParmModTable

Lua: table ParmModTable = ultraschall.CreateDefaultParmModTable()

returns a parameter-modulation-table with default settings set. You can alter these settings to your needs before committing it to an FXStateChunk.

The checkboxes for "Audio control signal (sidechain)", "LFO", "Link from MIDI or FX parameter" are unchecked and the fx-parameter is set to 1(the first parameter of the plugin). To enable and change them, you need to alter the following entries accordingly, or applying the ParmModTable has no effect:

    ParmModTable["AUDIOCONTROL"] - the checkbox for "Audio control signal (sidechain)"
    ParmModTable["LFO"]      - the checkbox for "LFO"
    ParmModTable["PARMLINK"] - the checkbox for "Link from MIDI or FX parameter"
    ParmModTable["PARAM_NR"] - the index of the fx-parameter for which the parameter-modulation-table is intended

The table's format and its default-values is as follows:

ParmModTable["PARAM_NR"] - the parameter that you want to modulate; 1 for the first, 2 for the second, etc ParmModTable["PARAM_TYPE"] - the type of the parameter, usually "", "wet" or "bypass"

ParmModTable["PARAMODENABLEPARAMETER_MODULATION"] - Enable parameter modulation, baseline value(envelope overrides)-checkbox; true, checked; false, unchecked ParmModTable["PARAMOD_BASELINE"] - Enable parameter modulation, baseline value(envelope overrides)-slider; 0.000 to 1.000

ParmModTable["AUDIOCONTROL"] - is the Audio control signal(sidechain)-checkbox checked; true, checked; false, unchecked Note: if true, this needs all AUDIOCONTROL-entries to be set ParmModTable["AUDIOCONTROL_CHAN"] - the Track audio channel-dropdownlist; When stereo, the first stereo-channel; nil, if not available ParmModTable["AUDIOCONTROL_STEREO"] - 0, just use mono-channels; 1, use the channel AUDIOCONTROLCHAN plus AUDIOCONTROLCHAN+1; nil, if not available ParmModTable["AUDIOCONTROL_ATTACK"] - the Attack-slider of Audio Control Signal; 0-1000 ms; nil, if not available ParmModTable["AUDIOCONTROL_RELEASE"] - the Release-slider; 0-1000ms; nil, if not available ParmModTable["AUDIOCONTROL_MINVOLUME"] - the Min volume-slider; -60dB to 11.9dB; must be smaller than AUDIOCONTROLMAXVOLUME; nil, if not available ParmModTable["AUDIOCONTROL_MAXVOLUME"] - the Max volume-slider; -59.9dB to 12dB; must be bigger than AUDIOCONTROL_MINVOLUME; nil, if not available ParmModTable["AUDIOCONTROL_STRENGTH"] - the Strength-slider; 0(0%) to 1000(100%) ParmModTable["AUDIOCONTROL_DIRECTION"] - the direction-radiobuttons; -1, negative; 0, centered; 1, positive ParmModTable["X2"]=0.5 - the audiocontrol signal shaping-x-coordinate ParmModTable["Y2"]=0.5 - the audiocontrol signal shaping-y-coordinate

ParmModTable["LFO"] - if the LFO-checkbox checked; true, checked; false, unchecked Note: if true, this needs all LFO-entries to be set ParmModTable["LFO_SHAPE"] - the LFO Shape-dropdownlist; 0, sine; 1, square; 2, saw L; 3, saw R; 4, triangle; 5, random nil, if not available ParmModTable["LFO_SHAPEOLD"] - use the old-style of the LFOSHAPE; 0, use current style of LFOSHAPE; 1, use old style of LFOSHAPE; nil, if not available ParmModTable["LFO_TEMPOSYNC"] - the Tempo sync-checkbox; true, checked; false, unchecked ParmModTable["LFO_SPEED"] - the LFO Speed-slider; 0(0.0039Hz) to 1(8.0000Hz); nil, if not available ParmModTable["LFO_STRENGTH"] - the LFO Strength-slider; 0.000(0.0%) to 1.000(100.0%) ParmModTable["LFO_PHASE"] - the LFO Phase-slider; 0.000 to 1.000; nil, if not available ParmModTable["LFO_DIRECTION"] - the LFO Direction-radiobuttons; -1, Negative; 0, Centered; 1, Positive ParmModTable["LFO_PHASERESET"] - the LFO Phase reset-dropdownlist; 0, On seek/loop(deterministic output) 1, Free-running(non-deterministic output) nil, if not available

ParmModTable["MIDIPLINK"] - true, if any parameter-linking with MIDI-stuff; false, if not Note: if true, this needs all MIDIPLINK-entries and PARMLINKLINKEDPLUGIN=-100 to be set ParmModTable["PARMLINK"] - the Link from MIDI or FX parameter-checkbox true, checked; false, unchecked ParmModTable["PARMLINK_LINKEDPLUGIN"] - the selected plugin; nil, if not available - will be ignored, when PARMLINKLINKEDPLUGINRELATIVE is set -1, nothing selected yet -100, MIDI-parameter-settings 1 - the first fx-plugin 2 - the second fx-plugin 3 - the third fx-plugin, etc ParmModTable["PARMLINKLINKEDPLUGINRELATIVE"] - the linked plugin relative to the current one in the FXChain - 0, use parameter of the current fx-plugin - negative, use parameter of a plugin above of the current plugin(-1, the one above; -2, two above, etc) - positive, use parameter of a plugin below the current plugin(1, the one below; 2, two below, etc) - nil, use only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX) ParmModTable["PARMLINK_LINKEDPARMIDX"] - the id of the linked parameter; -1, if none is linked yet; nil, if not available When MIDI, this is irrelevant. When FX-parameter: 0 to n; 0 for the first; 1, for the second, etc

ParmModTable["PARMLINK_OFFSET"] - the Offset-slider; -1.00(-100%) to 1.00(+100%); nil, if not available ParmModTable["PARMLINK_SCALE"] - the Scale-slider; -1.00(-100%) to 1.00(+100%); nil, if not available

ParmModTable["MIDIPLINK"] - true, if any parameter-linking with MIDI-stuff; false, if not Note: if true, this needs all MIDIPLINK-entries and PARMLINKLINKEDPLUGIN=-100 to be set ParmModTable["MIDIPLINK_BUS"] - the MIDI-bus selected in the button-menu; 0 to 15 for bus 1 to 16; nil, if not available ParmModTable["MIDIPLINK_CHANNEL"] - the MIDI-channel selected in the button-menu; 0, omni; 1 to 16 for channel 1 to 16; nil, if not available ParmModTable["MIDIPLINK_MIDICATEGORY"] - the MIDICategory selected in the button-menu; nil, if not available 144, MIDI note 160, Aftertouch 176, CC 14Bit and CC 192, Program Change 208, Channel Pressure 224, Pitch ParmModTable["MIDIPLINK_MIDINOTE"] - the MIDI-note selected in the button-menu; nil, if not available When MIDI note: 0(C-2) to 127(G8) When Aftertouch: 0(C-2) to 127(G8) When CC14 Bit: 128 to 159; see dropdownlist for the commands(the order of the list is the same as this numbering) When CC: 0 to 119; see dropdownlist for the commands(the order of the list is the same as this numbering) When Program Change: 0 When Channel Pressure: 0 When Pitch: 0 ParmModTable["WINDOW_ALTERED"] - false, if the windowposition hasn't been altered yet; true, if the window has been altered Note: if true, this needs all WINDOW-entries to be set ParmModTable["WINDOW_ALTEREDOPEN"] - if the position of the ParmMod-window is altered and currently open; nil, unchanged; 0, unopened; 1, open ParmModTable["WINDOW_XPOS"] - the x-position of the altered ParmMod-window in pixels; nil, default position ParmModTable["WINDOW_YPOS"] - the y-position of the altered ParmMod-window in pixels; nil, default position ParmModTable["WINDOW_RIGHT"] - the right-position of the altered ParmMod-window in pixels; nil, default position; only readable ParmModTable["WINDOW_BOTTOM"] - the bottom-position of the altered ParmMod-window in pixels; nil, default position; only readable


Returnvalues:
table ParmModTable
a ParmModTable with all settings set to Reaper's defaults


^ Reaper version 6.10 Ultraschall version 4.1DeleteParmModFromFXStateChunk

Lua: string altered_FXStateChunk, boolean altered = ultraschall.DeleteParmModFromFXStateChunk(string FXStateChunk, integer fxindex, integer parmidx)

deletes a parameter-modulation of a specific fx from an FXStateChunk

retval altered returns false in case of an error

Returnvalues:
string altered_FXStateChunk
the FXStateChunk, from which the
boolean altered
true, deleting was successful; false, deleting was unsuccessful

Parameters:
string FXStateChunk
the FXStateChunk from which you want to delete a parameter-modulation of a specific fx
integer fxindex
the index of the fx, whose parameter-modulations you want to delete
integer parmmodidx
the parameter-index, whose parameter-modulation you want to delete


^ Reaper version 6.02 Ultraschall version 4.1GetParmModTable_FXStateChunk

Lua: table ParmModulationTable = ultraschall.GetParmModTable_FXStateChunk(string FXStateChunk, integer fxindex, integer parmodindex)

Returns a table with all values of a specific Parameter-Modulation from an FXStateChunk.

The table's format is as follows:

ParmModTable["PARAM_NR"]                - the parameter that you want to modulate; 1 for the first, 2 for the second, etc
ParmModTable["PARAM_TYPE"]              - the type of the parameter, usually "", "wet" or "bypass"

ParmModTable["PARAMOD_ENABLE_PARAMETER_MODULATION"] 
                                        - Enable parameter modulation, baseline value(envelope overrides)-checkbox; 
                                          true, checked; false, unchecked
ParmModTable["PARAMOD_BASELINE"]        - Enable parameter modulation, baseline value(envelope overrides)-slider; 
                                            0.000 to 1.000

ParmModTable["AUDIOCONTROL"]            - is the Audio control signal(sidechain)-checkbox checked; true, checked; false, unchecked
                                            Note: if true, this needs all AUDIOCONTROL_-entries to be set
ParmModTable["AUDIOCONTROL_CHAN"]       - the Track audio channel-dropdownlist; When stereo, the first stereo-channel;
                                          nil, if not available
ParmModTable["AUDIOCONTROL_STEREO"]     - 0, just use mono-channels; 1, use the channel AUDIOCONTROL_CHAN plus 
                                            AUDIOCONTROL_CHAN+1; nil, if not available
ParmModTable["AUDIOCONTROL_ATTACK"]     - the Attack-slider of Audio Control Signal; 0-1000 ms; nil, if not available
ParmModTable["AUDIOCONTROL_RELEASE"]    - the Release-slider; 0-1000ms; nil, if not available
ParmModTable["AUDIOCONTROL_MINVOLUME"]  - the Min volume-slider; -60dB to 11.9dB; must be smaller than AUDIOCONTROL_MAXVOLUME; 
                                          nil, if not available
ParmModTable["AUDIOCONTROL_MAXVOLUME"]  - the Max volume-slider; -59.9dB to 12dB; must be bigger than AUDIOCONTROL_MINVOLUME; 
                                          nil, if not available
ParmModTable["AUDIOCONTROL_STRENGTH"]   - the Strength-slider; 0(0%) to 1000(100%)
ParmModTable["AUDIOCONTROL_DIRECTION"]  - the direction-radiobuttons; -1, negative; 0, centered; 1, positive
ParmModTable["X2"]=0.5                  - the audiocontrol signal shaping-x-coordinate
ParmModTable["Y2"]=0.5                  - the audiocontrol signal shaping-y-coordinate    

ParmModTable["LFO"]                     - if the LFO-checkbox checked; true, checked; false, unchecked
                                            Note: if true, this needs all LFO_-entries to be set
ParmModTable["LFO_SHAPE"]               - the LFO Shape-dropdownlist; 
                                            0, sine; 1, square; 2, saw L; 3, saw R; 4, triangle; 5, random
                                            nil, if not available
ParmModTable["LFO_SHAPEOLD"]            - use the old-style of the LFO_SHAPE; 
                                            0, use current style of LFO_SHAPE; 
                                            1, use old style of LFO_SHAPE; 
                                            nil, if not available
ParmModTable["LFO_TEMPOSYNC"]           - the Tempo sync-checkbox; true, checked; false, unchecked
ParmModTable["LFO_SPEED"]               - the LFO Speed-slider; 0(0.0039Hz) to 1(8.0000Hz); nil, if not available
ParmModTable["LFO_STRENGTH"]            - the LFO Strength-slider; 0.000(0.0%) to 1.000(100.0%)
ParmModTable["LFO_PHASE"]               - the LFO Phase-slider; 0.000 to 1.000; nil, if not available
ParmModTable["LFO_DIRECTION"]           - the LFO Direction-radiobuttons; -1, Negative; 0, Centered; 1, Positive
ParmModTable["LFO_PHASERESET"]          - the LFO Phase reset-dropdownlist; 
                                            0, On seek/loop(deterministic output)
                                            1, Free-running(non-deterministic output)
                                            nil, if not available

ParmModTable["MIDIPLINK"]               - true, if any parameter-linking with MIDI-stuff; false, if not
                                            Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
ParmModTable["PARMLINK"]                - the Link from MIDI or FX parameter-checkbox
                                          true, checked; false, unchecked
ParmModTable["PARMLINK_LINKEDPLUGIN"]   - the selected plugin; nil, if not available
                                        - will be ignored, when PARMLINK_LINKEDPLUGIN_RELATIVE is set
                                            -1, nothing selected yet
                                            -100, MIDI-parameter-settings
                                            1 - the first fx-plugin
                                            2 - the second fx-plugin
                                            3 - the third fx-plugin, etc
ParmModTable["PARMLINK_LINKEDPLUGIN_RELATIVE"] - the linked plugin relative to the current one in the FXChain
                                               - 0, use parameter of the current fx-plugin
                                               - negative, use parameter of a plugin above of the current plugin(-1, the one above; -2, two above, etc)
                                               - positive, use parameter of a plugin below the current plugin(1, the one below; 2, two below, etc)
                                               - nil, use only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX)
ParmModTable["PARMLINK_LINKEDPARMIDX"]  - the id of the linked parameter; -1, if none is linked yet; nil, if not available
                                            When MIDI, this is irrelevant.
                                            When FX-parameter:
                                              0 to n; 0 for the first; 1, for the second, etc

ParmModTable["PARMLINK_OFFSET"]         - the Offset-slider; -1.00(-100%) to 1.00(+100%); nil, if not available
ParmModTable["PARMLINK_SCALE"]          - the Scale-slider; -1.00(-100%) to 1.00(+100%); nil, if not available

ParmModTable["MIDIPLINK"]               - true, if any parameter-linking with MIDI-stuff; false, if not
                                            Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
ParmModTable["MIDIPLINK_BUS"]           - the MIDI-bus selected in the button-menu; 
                                            0 to 15 for bus 1 to 16; 
                                            nil, if not available
ParmModTable["MIDIPLINK_CHANNEL"]       - the MIDI-channel selected in the button-menu; 
                                            0, omni; 1 to 16 for channel 1 to 16; 
                                            nil, if not available
ParmModTable["MIDIPLINK_MIDICATEGORY"]  - the MIDI_Category selected in the button-menu; nil, if not available
                                            144, MIDI note
                                            160, Aftertouch
                                            176, CC 14Bit and CC
                                            192, Program Change
                                            208, Channel Pressure
                                            224, Pitch
ParmModTable["MIDIPLINK_MIDINOTE"]      - the MIDI-note selected in the button-menu; nil, if not available
                                          When MIDI note:
                                               0(C-2) to 127(G8)
                                          When Aftertouch:
                                               0(C-2) to 127(G8)
                                          When CC14 Bit:
                                               128 to 159; see dropdownlist for the commands(the order of the list 
                                               is the same as this numbering)
                                          When CC:
                                               0 to 119; see dropdownlist for the commands(the order of the list 
                                               is the same as this numbering)
                                          When Program Change:
                                               0
                                          When Channel Pressure:
                                               0
                                          When Pitch:
                                               0
ParmModTable["WINDOW_ALTERED"]          - false, if the windowposition hasn't been altered yet; true, if the window has been altered
                                            Note: if true, this needs all WINDOW_-entries to be set
ParmModTable["WINDOW_ALTEREDOPEN"]      - if the position of the ParmMod-window is altered and currently open; 
                                            nil, unchanged; 0, unopened; 1, open
ParmModTable["WINDOW_XPOS"]             - the x-position of the altered ParmMod-window in pixels; nil, default position
ParmModTable["WINDOW_YPOS"]             - the y-position of the altered ParmMod-window in pixels; nil, default position
ParmModTable["WINDOW_RIGHT"]            - the right-position of the altered ParmMod-window in pixels; 
                                            nil, default position; only readable
ParmModTable["WINDOW_BOTTOM"]           - the bottom-position of the altered ParmMod-window in pixels; 
                                            nil, default position; only readable

returns nil in case of an error


Returnvalues:
table ParmModulationTable
a table which holds all values of a specfic parameter-modulation

Parameters:
string FXStateChunk
an FXStateChunk, of which you want to get the values of a specific parameter-modulation
integer fxindex
the index if the fx, of which you want to get specific parameter-modulation-values
integer parmodindex
the parameter-modulation, whose values you want to get; 1, for the first; 2, for the second, etc


^ Reaper version 5.975 Ultraschall version 4.00GetParmModulationChunk_FXStateChunk

Lua: string parm_modulation_chunk = ultraschall.GetParmModulationChunk_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Returns a parameter-modulation-chunk from an FXStateChunk
An FXStateChunk holds all FX-plugin-settings for a specific MediaTrack or MediaItem.

It's the
Returns nil in case of an error

Returnvalues:
string parm_modulation_chunk
a chunk of the parameter-modulation settings

Parameters:
string FXStateChunk
the FXStateChunk, from which you want to retrieve the Parameter-modulation-settings
integer fxid
the fx, of which you want to get the parameter-modulation-chunk-settings
integer id
the id of the Parameter-modulation you want to have, starting with 1 for the first


^ Reaper version 6.10 Ultraschall version 4.1IsValidParmModTable

Lua: boolean retval = ultraschall.IsValidParmModTable(table ParmModTable)

checks, if a ParmModTable is a valid one

Does not check, if the value-ranges are valid, only if the datatypes are correct and if certain combinations are valid!

Use SLEM() to get error-messages who tell you, which entries are problematic.

returns false in case of an error

Returnvalues:
boolean retval
true, ParmModTable is a valid one; false, ParmModTable has errors(use SLEM() to get which one)

Parameters:
table ParmModTable
the table to check, if it's a valid ParmModTable


^ Reaper version 6.02 Ultraschall version 4.1SetParmMod_ParmModTable

Lua: string FXStateChunk = ultraschall.SetParmMod_ParmModTable(string FXStateChunk, integer fxindex, table ParmModTable)

Takes a ParmModTable and sets its values into a Parameter Modulation of a specific fx within an FXStateChunk.
  
The expected table's format is as follows:

    ParmModTable["PARAM_NR"]                - the parameter that you want to modulate; 1 for the first, 2 for the second, etc
    ParmModTable["PARAM_TYPE"]              - the type of the parameter, usually "", "wet" or "bypass"

    ParmModTable["PARAMOD_ENABLE_PARAMETER_MODULATION"]
                                            - Enable parameter modulation, baseline value(envelope overrides)-checkbox;
                                              true, checked; false, unchecked
    ParmModTable["PARAMOD_BASELINE"]        - Enable parameter modulation, baseline value(envelope overrides)-slider;
                                                0.000 to 1.000

    ParmModTable["AUDIOCONTROL"]            - is the Audio control signal(sidechain)-checkbox checked; true, checked; false, unchecked
                                                Note: if true, this needs all AUDIOCONTROL_-entries to be set
    ParmModTable["AUDIOCONTROL_CHAN"]       - the Track audio channel-dropdownlist; When stereo, the first stereo-channel;
                                              nil, if not available
    ParmModTable["AUDIOCONTROL_STEREO"]     - 0, just use mono-channels; 1, use the channel AUDIOCONTROL_CHAN plus
                                                AUDIOCONTROL_CHAN+1; nil, if not available
    ParmModTable["AUDIOCONTROL_ATTACK"]     - the Attack-slider of Audio Control Signal; 0-1000 ms; nil, if not available
    ParmModTable["AUDIOCONTROL_RELEASE"]    - the Release-slider; 0-1000ms; nil, if not available
    ParmModTable["AUDIOCONTROL_MINVOLUME"]  - the Min volume-slider; -60dB to 11.9dB; must be smaller than AUDIOCONTROL_MAXVOLUME;
                                              nil, if not available
    ParmModTable["AUDIOCONTROL_MAXVOLUME"]  - the Max volume-slider; -59.9dB to 12dB; must be bigger than AUDIOCONTROL_MINVOLUME;
                                              nil, if not available
    ParmModTable["AUDIOCONTROL_STRENGTH"]   - the Strength-slider; 0(0%) to 1000(100%)
    ParmModTable["AUDIOCONTROL_DIRECTION"]  - the direction-radiobuttons; -1, negative; 0, centered; 1, positive
    ParmModTable["X2"]=0.5                  - the audiocontrol signal shaping-x-coordinate
    ParmModTable["Y2"]=0.5                  - the audiocontrol signal shaping-y-coordinate    
    
    ParmModTable["LFO"]                     - if the LFO-checkbox checked; true, checked; false, unchecked
                                                Note: if true, this needs all LFO_-entries to be set
    ParmModTable["LFO_SHAPE"]               - the LFO Shape-dropdownlist;
                                                0, sine; 1, square; 2, saw L; 3, saw R; 4, triangle; 5, random
                                                nil, if not available
    ParmModTable["LFO_SHAPEOLD"]            - use the old-style of the LFO_SHAPE;
                                                0, use current style of LFO_SHAPE;
                                                1, use old style of LFO_SHAPE;
                                                nil, if not available
    ParmModTable["LFO_TEMPOSYNC"]           - the Tempo sync-checkbox; true, checked; false, unchecked
    ParmModTable["LFO_SPEED"]               - the LFO Speed-slider; 0(0.0039Hz) to 1(8.0000Hz); nil, if not available
    ParmModTable["LFO_STRENGTH"]            - the LFO Strength-slider; 0.000(0.0%) to 1.000(100.0%)
    ParmModTable["LFO_PHASE"]               - the LFO Phase-slider; 0.000 to 1.000; nil, if not available
    ParmModTable["LFO_DIRECTION"]           - the LFO Direction-radiobuttons; -1, Negative; 0, Centered; 1, Positive
    ParmModTable["LFO_PHASERESET"]          - the LFO Phase reset-dropdownlist;
                                                0, On seek/loop(deterministic output)
                                                1, Free-running(non-deterministic output)
                                                nil, if not available
    
    ParmModTable["MIDIPLINK"]               - true, if any parameter-linking with MIDI-stuff; false, if not
                                                Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
    ParmModTable["PARMLINK"]                - the Link from MIDI or FX parameter-checkbox
                                              true, checked; false, unchecked
    ParmModTable["PARMLINK_LINKEDPLUGIN"]   - the selected plugin; nil, if not available
                                            - will be ignored, when PARMLINK_LINKEDPLUGIN_RELATIVE is set
                                                -1, nothing selected yet
                                                -100, MIDI-parameter-settings
                                                1 - the first fx-plugin
                                                2 - the second fx-plugin
                                                3 - the third fx-plugin, etc
    ParmModTable["PARMLINK_LINKEDPLUGIN_RELATIVE"] - the linked plugin relative to the current one in the FXChain
                                                   - 0, use parameter of the current fx-plugin
                                                   - negative, use parameter of a plugin above of the current plugin(-1, the one above; -2, two above, etc)
                                                   - positive, use parameter of a plugin below the current plugin(1, the one below; 2, two below, etc)
                                                   - nil, use only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX)
    ParmModTable["PARMLINK_LINKEDPARMIDX"]  - the id of the linked parameter; -1, if none is linked yet; nil, if not available
                                                When MIDI, this is irrelevant.
                                                When FX-parameter:
                                                  0 to n; 0 for the first; 1, for the second, etc

    ParmModTable["PARMLINK_OFFSET"]         - the Offset-slider; -1.00(-100%) to 1.00(+100%); nil, if not available
    ParmModTable["PARMLINK_SCALE"]          - the Scale-slider; -1.00(-100%) to 1.00(+100%); nil, if not available

    ParmModTable["MIDIPLINK"]               - true, if any parameter-linking with MIDI-stuff; false, if not
                                                Note: if true, this needs all MIDIPLINK_-entries and PARMLINK_LINKEDPLUGIN=-100 to be set
    ParmModTable["MIDIPLINK_BUS"]           - the MIDI-bus selected in the button-menu;
                                                0 to 15 for bus 1 to 16;
                                                nil, if not available
    ParmModTable["MIDIPLINK_CHANNEL"]       - the MIDI-channel selected in the button-menu;
                                                0, omni; 1 to 16 for channel 1 to 16;
                                                nil, if not available
    ParmModTable["MIDIPLINK_MIDICATEGORY"]  - the MIDI_Category selected in the button-menu; nil, if not available
                                                144, MIDI note
                                                160, Aftertouch
                                                176, CC 14Bit and CC
                                                192, Program Change
                                                208, Channel Pressure
                                                224, Pitch
    ParmModTable["MIDIPLINK_MIDINOTE"]      - the MIDI-note selected in the button-menu; nil, if not available
                                              When MIDI note:
                                                   0(C-2) to 127(G8)
                                              When Aftertouch:
                                                   0(C-2) to 127(G8)
                                              When CC14 Bit:
                                                   128 to 159; see dropdownlist for the commands(the order of the list
                                                   is the same as this numbering)
                                              When CC:
                                                   0 to 119; see dropdownlist for the commands(the order of the list
                                                   is the same as this numbering)
                                              When Program Change:
                                                   0
                                              When Channel Pressure:
                                                   0
                                              When Pitch:
                                                   0
    ParmModTable["WINDOW_ALTERED"]          - false, if the windowposition hasn't been altered yet; true, if the window has been altered
                                                Note: if true, this needs all WINDOW_-entries to be set
    ParmModTable["WINDOW_ALTEREDOPEN"]      - if the position of the ParmMod-window is altered and currently open;
                                                        nil, unchanged; 0, unopened; 1, open
    ParmModTable["WINDOW_XPOS"]             - the x-position of the altered ParmMod-window in pixels; nil, default position
    ParmModTable["WINDOW_YPOS"]             - the y-position of the altered ParmMod-window in pixels; nil, default position
    ParmModTable["WINDOW_RIGHT"]            - the right-position of the altered ParmMod-window in pixels;
                                                nil, default position; only readable
    ParmModTable["WINDOW_BOTTOM"]           - the bottom-position of the altered ParmMod-window in pixels;
                                                nil, default position; only readable

This function does not check, if the values are within valid value-ranges, only if the datatypes are valid.

Note: If you want to apply a ParmModulationTable from a bypass/wet-parameter to a non bypass/wet-parameter, you need to set ParmModTable["PARAM_TYPE"]="" or it will remove the parameter-modulation!
Also note: set ParmModTable["PARAM_NR"] to choose the parameter-index, whose ParameterModulation shall be set.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk, where the ParameterModulation had been set

Parameters:
string FXStateChunk
an FXStateChunk, of which you want to set the values of a specific parameter-modulation
integer fxindex
the index if the fx, of which you want to set specific parameter-modulation-values
table ParmModTable
the table which holds all parameter-modulation-values to be set


^ Reaper version 5.977 SWS version 2.10.0.1 JS version 0.986 Ultraschall version 4.00AutoDetectVSTPluginsFolder

Lua: ultraschall.AutoDetectVSTPluginsFolder()

Auto-detects the vst-plugins-folder.


^ Reaper version 5.977 SWS version 2.10.0.1 JS version 0.986 Ultraschall version 4.00ScanDXPlugins

Lua: ultraschall.ScanDXPlugins(optional boolean re_scan)

(Re-)scans all DX-Plugins.

Parameters:
optional boolean clear_cache
true, re-scan all DX-plugins; false or nil, only scan new DX-plugins


^ Reaper version 5.977 SWS version 2.10.0.1 JS version 0.986 Ultraschall version 4.00ScanVSTPlugins

Lua: ultraschall.ScanVSTPlugins(optional boolean clear_cache)

Re-scans all VST-Plugins.

Parameters:
optional boolean clear_cache
true, clear cache before re-scanning; false or nil, just scan vts-plugins


^ Reaper version 6.19 Ultraschall version 4.2SetDocked_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetDocked_FXStateChunk(string FXStateChunk, integer docked)

sets the docked-state of an FXStateChunk.

It is the DOCKED-entry

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new DOCKED-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new last-selected-fx-state
integer docked
the docked-state of the fx-chain-window; 0, undocked; 1, docked


^ Reaper version 6.19 Ultraschall version 4.2SetFXBypass_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXBypass_FXStateChunk(string FXStateChunk, integer fxid, integer bypass, integer offline, integer unknown)

sets the fx-BYPASS-entry of a specific fx within an FXStateChunk, which allows setting online/offline and bypass-settings.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new BYPASS-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new bypass-state
integer fxid
the fx, whose bypass-state you want to set
integer bypass
0, non-bypassed; 1, bypassed
integer offline
0, online; 1, offline
integer unknown
unknown; default is 0


^ Reaper version 6.02 Ultraschall version 4.2SetFXComment_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXComment_FXStateChunk(string FXStateChunk, integer fxid, string NewComment)

sets an fx-comment of a specific fx within an FXStateChunk

Set to "" to remove the comment

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new comment

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new comment
integer fxid
the fx, whose comment you want to set
string NewComment
the new comment; "", to remove the currently set comment; newlines are allowed


^ Reaper version 6.19 Ultraschall version 4.2SetFXFloatPos_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXFloatPos_FXStateChunk(string FXStateChunk, integer fxid, boolean floating, integer x, integer y, integer w, integer h)

sets the fx-FXID-entry of a specific fx within an FXStateChunk, which manages floatstate and position of the floating-fx-window.

Note: when committing it to a track/item of an opened project, keep in mind that setting floating=false will have no effect.
You will also need to commit a TrackStateChunk/ItemStateChunk twice, as in the first commit, w and h will be ignored if the fx isn't already floating.
This is probably due a Reaper bug and I can't fix it in here, sorry.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new BYPASS-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new bypass-state
integer fxid
the fx, whose bypass-state you want to set
boolean floating
true, window is floating; false, window is not floating
integer x
the x-position of the floating-window
integer y
the y-position of the floating-window
integer w
the width of the window(will be ignored, when committing changed statechunk only once to current project's track/item)
integer h
the height of the window(will be ignored, when committing changed statechunk only once to current project's track/item)


^ Reaper version 6.19 Ultraschall version 4.2SetFXGuid_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXGuid_FXStateChunk(string FXStateChunk, integer fxid, string guid)

sets the fx-FXID-entry of a specific fx within an FXStateChunk, which holds the guid for this fx.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new BYPASS-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new gui
integer fxid
the fx, whose guid you want to set
string guid
a guid for this fx; use reaper.genGuid to create one


^ Reaper version 6.02 Ultraschall version 4.2SetFXMidiPreset_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXMidiPreset_FXStateChunk(string FXStateChunk, integer fxid, integer midi_preset)

sets the MIDIPRESET-entryvalues of a specific fx from an FXStateChunk as set by the +-button->Link to MIDI program change-menuentry in the FX-window of the visible plugin.

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new comment

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new comment
integer fxid
the fx, whose comment you want to set
integer midi_preset
0, No Link; 17, Link all channels sequentially; 1-16, MIDI-channel 1-16


^ Reaper version 6.19 Ultraschall version 4.2SetFXWak_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetFXWak_FXStateChunk(string FXStateChunk, integer fxid, integer send_all_keyboard_input_to_fx, integer fx_embed_state)

sets the fx-WAK-entry of a specific fx within an FXStateChunk, which allows setting "sending all keyboard input to plugin"-option and "embed fx in tcp/mcp"-option of an fx

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new wak-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new wak-state
integer fxid
the fx, whose wak-state you want to set
integer send_all_keyboard_input_to_fx
state of sen all keyboard input to plug-in; 0, turned off; 1, turned on
integer fx_embed_state
set embedding of the fx; &1=TCP, &2=MCP


^ Reaper version 6.19 Ultraschall version 4.2SetLastSel_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetLastSel_FXStateChunk(string FXStateChunk, integer lastsel)

sets the last selected-plugin of an FXStateChunk.

It is the LASTSEL-entry

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new LASTSEL-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new last-selected-fx-state
integer lastsel
the last fx selected; 1, for the first fx; 2, for the second fx; etc


^ Reaper version 6.19 Ultraschall version 4.2SetShow_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetShow_FXStateChunk(string FXStateChunk, integer showstate)

sets the shown-plugin of an FXStateChunk.

It is the SHOW-entry

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new SHOW-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new shown-fx-state
integer showstate
the fx shown; 1, for the first fx; 2, for the second fx; etc


^ Reaper version 6.10 Ultraschall version 4.2SetTakeFXComment

Lua: string comment = ultraschall.SetTakeFXComment(MediaItem item, integer takeid, integer fxid, string Comment)

sets the comment of a take-fx

returns nil in case of an error

Returnvalues:
string comment
the comment of a track-fx

Parameters:
MediaItem item
the mediaitem, whose takefx-comment you want to set
integer take_id
the id of the take, whose takefx-comment you want to set
integer fxid
the id of the fx, whose comment you want to set
string Comment
the new Comment for this takefx


^ Reaper version 6.11 Ultraschall version 4.1SetTakeFX_AlternativeName

Lua: boolean retval = ultraschall.SetTakeFX_AlternativeName(integer tracknumber, integer take_id, integer fx_id, string newname)

sets the alternative name of a specific takefx.

Returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful


^ Reaper version 6.10 Ultraschall version 4.2SetTrackFXComment

Lua: boolean retval = ultraschall.SetTrackFXComment(MediaTrack track, integer fxid, string Comment)

sets the comment of a track-fx

Note: you need to switch fxchain off/on or change the shown fx for the new comment to be displayed in Reaper's UI

returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful

Parameters:
MediaTrack track
the mediatrack, of which you want to set a trackfx's comment
integer fxid
the id of the fx, whose comment you want to set
string Comment
the new comment


^ Reaper version 6.11 Ultraschall version 4.1SetTrackFX_AlternativeName

Lua: boolean retval = ultraschall.SetTrackFX_AlternativeName(integer tracknumber, integer fx_id, string newname)

sets the alternative name of a specific trackfx.

Returns false in case of an error

Returnvalues:
boolean retval
true, setting was successful; false, setting was unsuccessful


^ Reaper version 6.19 Ultraschall version 4.2SetWndRect_FXStateChunk

Lua: string FXStateChunk = ultraschall.SetWndRect_FXStateChunk(string FXStateChunk, integer x, integer y, integer w, integer h)

sets the docked-state of an FXStateChunk.

It is the WNDRECT-entry

returns nil in case of an error

Returnvalues:
string FXStateChunk
the altered FXStateChunk with the new WNDRECT-state

Parameters:
string FXStateChunk
the FXStateChunk, into which you want to set the new undocked-windowposition-state
integer x
the x-position of the undocked window
integer y
the y-position of the undocked window
integer w
the width of the window-rectangle
integer h
the height of the window-rectangle


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_AddFileToQueue

Lua: integer current_copyqueue_position = ultraschall.CopyFile_AddFileToQueue(string filename, string targetfilename, boolean overwrite)

Adds a new file to the copy-queue.

If you try to copy a file into a subdirectory, which does not exist yet, this subdirectory will be created.
If the background-copying is still active(the copying-queue not finished with copying) at the time of adding, the file will be copied right away.
To check, whether you need to start if there are still running copying-instances in the background, use CopyFile_IsCurrentlyCopying.

The returned value in current_copyqueue_position allows you get the current copying status and possible error-messages using CopyFile_GetCopiedStatus

returns -1 in case of an error.


Returnvalues:
integer current_copyqueue_position
the position in the copy-queue

Parameters:
string filename
the file to be copied, including its path
string targetfilename
the targetfile, to which the file shall be copied including its path
boolean overwrite
true, overwrite an already existing file; false, don't overwrite an already existing file


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_FlushCopiedFiles

Lua: ultraschall.CopyFile_FlushCopiedFiles()

Flushes the queue for the already copied files.

This invalidates the files-index given by CopyFile_AddFileToQueue!



^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetBufferSize

Lua: integer buffer_size = ultraschall.CopyFile_GetBufferSize()

Returns the current buffer-size in bytes.


Returnvalues:
integer buffer_size
the buffer-size for the copying instances in bytes


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetCopiedStatus

Lua: string filename, boolean already_processed, string error_message, string error_code = ultraschall.CopyFile_GetCopiedStatus(integer fileindex)

Returns the copystatus of a file in the copy-queue

Will return -1 in case of an error.


Returnvalues:
string filename
the filename of the file to be copied
boolean already_processed
true, files has been processed; false, the file has not been processed, yet
string error_message
the error-message, when copying didn't work; "" if no error occurred
string error_code
an error-code for the error happening

Parameters:
integer fileindex
the index of the file within the copying-queue


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetCurrentlyCopiedFile

Lua: integer number_of_remaining_files, string filename, integer remaining_bytes_to_copy, integer percentage = ultraschall.CopyFile_GetCurrentlyCopiedFile()

Returns the information about the file currently copied


Returnvalues:
integer number_of_remaining_files
the number of files still in the copying-queue
string filename
the filename with path of the file currently copied
integer remaining_bytes_to_copy
the number of bytes not copied yet of the current file
integer percentage
the percentage of the already copied part of the file


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetCurrentlyRunningCopyInstances

Lua: integer number_of_instances = ultraschall.CopyFile_GetCurrentlyRunningCopyInstances()

Returns the number of copying-instances currently started by CopyFile_StartCopying


Returnvalues:
integer number_of_instances
the number of copying instances started


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetPausedState

Lua: boolean retval = ultraschall.CopyFile_GetPausedState()

Returns the current paused-state of the background-copying


Returnvalues:
boolean retval
true, copying is paused; false, copying isn't paused


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_GetRemainingFilesToCopy

Lua: integer filecount = ultraschall.CopyFile_GetRemainingFilesToCopy()

Returns the number of files that still need to be copied.


Returnvalues:
integer filecount
the number of files to be copied


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_IsCurrentlyCopying

Lua: boolean retval = ultraschall.CopyFile_IsCurrentlyCopying()

Returns, if the any copying-instance is (still) currently copying files.


Returnvalues:
boolean retval
true, currently copying files; false, no file currently copying


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_Pause

Lua: boolean retval = ultraschall.CopyFile_Pause(boolean toggle)

Pauses the copying of the files in the copying-queue.

Will return false in case of an error.


Returnvalues:
boolean retval
true, pausing was successful; false, pausing was unsuccessful

Parameters:
integer toogle
true, pause the copying; false, go on with copying of the files


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_SetBufferSize

Lua: boolean retval = ultraschall.CopyFile_SetBufferSize(integer buffersize)

Sets the buffer-size of the background-copy-instances in bytes.

That means, each copying-instance will copy this amount of data per defer-cycle.

Returns false in case of an error.


Returnvalues:
boolean retval
true, setting this was successful; false, setting this was unsuccessful

Parameters:
integer buffersize
the amount of bytes of the buffer-size


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_StartCopying

Lua: integer instance_number = ultraschall.CopyFile_StartCopying()

Starts copying the files added to the background-copy-queue.

You can run this function multiple times, to have multiple background-copy-instances, depending on how fast the copying shall be and how much ressources it should eat. Each instance copies the amount of data set with CopyFile_SetBufferSize, so if the buffersize is set to 1048576(1 MB) then each instance will copy 1 MB per defer-cycle. That way you can balance the amount of data copied each defer-cycle with the amount of time each defer-cycle uses Reaper's processing-time. So having multiple instances with smaller buffer-sizes can prevent lagging of the gui of Reaper.

You can have up to 30 instances running in the background at the same time.

Add files with CopyFile_AddFileToQueue

If all files are copied, the instances will be stopped completely, so using CopyFile_GetCurrentlyRunningCopyInstances returning 0 can tell you, if the copying is finished already.

Will return -1, if all possible 30 instances are started already.


Returnvalues:
integer instance_number
the copying-instance started


^ Reaper version 5.40 Ultraschall version 4.1CopyFile_StopCopying

Lua: ultraschall.CopyFile_StopCopying()

Stops copying of all files immediately. If the currently file isn't finished copying yet, it will remain incomplete.

Returns the last file processed, so you can check, if the file has been copied properly.


Returnvalues:
string filename
the last filename that has been processed
string filename_target
the target of the last filename, that has been processed


^ Reaper version 5.40 Ultraschall version 4.00CheckForValidFileFormats

Lua: string fileformat, boolean supported_by_reaper, string mediatype = u