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



4.2.004 - "Grandma - kl" - 12th of June 2021 - Build: 43631

The Functions Reference

To add the API to your script after installing it, just add


        dofile(reaper.GetResourcePath().."/UserPlugins/ultraschall_api.lua")
      
as first line into your script.

For more details, read the docs in the Introduction and Concepts-area of this page.

API-Helper functions

ActionsList_GetAllActionsActionsList_GetSelectedActionsBenchmark_GetAllStartTimesAndSlotsBenchmark_GetStartTime
Benchmark_MeasureTimeBringReaScriptConsoleToFrontCharacterCodes_ReverseLookupCharacterCodes_ReverseLookup_KBIni
CheckActionCommandIDFormatCheckActionCommandIDFormatCheckActionCommandIDFormat2ConvertFunction_FromBase64String
ConvertFunction_FromHexStringConvertFunction_ToBase64StringConvertFunction_ToHexStringCreate2DTable
Create3DTableCreateMultiDimTableFloatCompareFromClip
GMem_GetValues_VideoSamplePeekerGMem_Read_ValueRangeGetAllActionsGetApiVersion
GetOSGetReaperAppVersionGetReaperColorThemesPathGetReaperJSFXPath
GetReaperScriptPathGetReaperWebRCPathGetScriptFilenameFromActionCommandIDGmem_GetCurrentAttachedName
IsItemInTrackIsItemInTrack2IsItemInTrack3IsOS_Mac
IsOS_OtherIsOS_WindowsIsObjectValidReaperObjectIsValidGuid
IsWithinTimeRangeKBIniGetAllShortcutsLoadFunctionFromExtStateMakeFunctionUndoable
OpenURLPingMePreventCreatingUndoPointPrintProgressBar
RefreshToolbar_ActionResetProgressBarReturnTypeOfReaperObjectReturnsMinusOneInCaseOfError_Arzala
RunBackgroundHelperFeaturesRunCommandRunLuaSourceCodeSetIntConfigVar_Bitfield
StoreFunctionInExtStateTimeToMeasuresToClipToggleStateAction
ToggleStateButtondeprecatedget_action_context_MediaItemDiffprint
print2print3print_altprint_update
tobooleantype 
Child Scripts
GetScriptIdentifierGetScriptIdentifier_DescriptionGetScriptIdentifier_TitleGetScriptParameters
GetScriptReturnvaluesGetScriptReturnvalues_SenderMIDI_OnCommandByFilenameMain_OnCommandByFilename
Main_OnCommand_LuaCodeSetScriptIdentifier_DescriptionSetScriptIdentifier_TitleSetScriptParameters
SetScriptReturnvalues  
Data Analysis
FindPatternsInString  
Data Manipulation
AddIntToCharBase64_DecoderBase64_EncoderCSV2IndividualLinesAsArray
CSV2LineCombineBytesToIntegerCompareArraysCompareStringWithAsciiValues
ConcatIntegerIndexedTablesConvertAscii2HexConvertBitsToIntegerConvertBitsToString
ConvertHex2AsciiConvertIntegerIntoString2ConvertIntegerToBitsConvertStringToAscii_Array
ConvertStringToBitsConvertStringToIntegersCountCharacterInStringCountEntriesInTable_Main
CountLinesInStringCountPatternInStringCycleTableDB2MKVOL
EscapeMagicCharacters_StringGetAllEntriesFromTableGetDuplicatesFromArraysGetPartialString
GetSetIntConfigVarIsValidMatchingPatternKeepTableEntriesOfTypeLimitFractionOfFloat
MKVOL2DBMakeCopyOfTableNotes2CSVRemoveTableEntriesOfType
ReplacePartOfStringReplacePatternInStringReturnTableAsIndividualValuesReverseEndianess_Byte
ReverseTableRoundNumberSearchStringInStringSecondsToTime
SecondsToTimeString_hh_mm_ss_mssSetBitfieldSplitIntegerIntoBytesSplitStringAtLineFeedToArray
SplitStringAtNULLBytesStateChunkLayouterTimeStringToSeconds_hh_mm_ss_mssTimeToSeconds
   

API-Variables

API_TempPathApi_InstallPathApi_PathEuro
SeparatorStartTime 

Audio Management

GetHWInputs_AliasnamesGetHWOutputs_Aliasnames 

Automation Items

AutomationItem_DeleteAutomationItem_SplitAutomationItems_GetAllAutomationItems_GetByTime
GetProject_AutomationItemStateChunkGetProject_CountAutomationItems 

Clipboard Functions

GetMediaItemsFromClipboardGetStringFromClipboard_SWSPutMediaItemsToClipboard_MediaItemArray

Color Management

ApplyColorTableToItemColorsApplyColorTableToTrackColorsChangeColorBrightnessChangeColorContrast
ChangeColorSaturationConvertColorConvertColorFromMacConvertColorFromWin
ConvertColorReverseConvertColorToGFXConvertColorToMacConvertColorToWin
ConvertGFXToColorCreateColorTableCreateSonicRainboomColorTableIsValidColorTable
RGB2Grayscale  

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_secCountKeysByPatternCountSectionsByPattern
CountValuesByPatternEnumerateIniFileExternalState_keyEnumerateIniFileExternalState_secEnumerateKeysByPattern
EnumerateSectionsByPatternEnumerateValuesByPatternGetIniFileExternalStateGetIniFileValue
SetIniFileExternalStateSetIniFileValue 
Reaper-kb.ini
CountKBIniActionsCountKBIniKeysCountKBIniScriptsDeleteKBIniActions
DeleteKBIniKeysDeleteKBIniScriptsGetActionCommandIDByFilenameGetKBIniActions
GetKBIniActionsID_ByActionCommandIDGetKBIniFilepathGetKBIniKeysGetKBIniKeys_ByActionCommandID
GetKBIniScriptsGetKBIniScripts_ByActionCommandIDQueryKeyboardShortcutByKeyIDSetKBIniActions
SetKBIniKeysSetKBIniScripts 

Defer-Management

DeferGetDeferCycleSettingsGetDeferRunStateSetDeferCycleSettings
StopDeferCycle  

Developer

Error Handling
AddErrorMessageCountErrorMessage_FuncnameCountErrorMessagesDeleteAllErrorMessages
DeleteErrorMessageDeleteLastErrorMessageGetErrorMessage_FuncnameGetLastErrorMessage
GetLastErrorMessage2GetLastErrorMessage_FuncnameReadErrorMessageSFEM
SLEMShowErrorMessagesInReascriptConsoleShowLastErrorMessageSuppressErrorMessages
ToggleIDE_Errormessages  
Helper functions
APIExistsApiTestEditReaScriptRFR
RLRRRR 

Envelope Management

ActivateTrackPanEnvActivateTrackPanEnv_TrackObjectActivateTrackPreFXPanEnvActivateTrackPreFXPanEnv_TrackObject
ActivateTrackPreFXVolumeEnvActivateTrackPreFXVolumeEnv_TrackObjectActivateTrackTrimVolumeEnvActivateTrackTrimVolumeEnv_TrackObject
ActivateTrackVolumeEnvActivateTrackVolumeEnv_TrackObject 
Envelopes
GetAllTakeEnvelopesGetAllTrackEnvelopesGetTakeEnvelopeUnderMouseCursorIsAnyMuteEnvelopeVisible
IsEnvelope_TrackIsTrackEnvelopeVisible_ArrangeView 
Get Envelope States
GetArmState_EnvelopeGetEnvelopeState_ActGetEnvelopeState_DefShapeGetEnvelopeState_EnvName
GetEnvelopeState_LaneHeightGetEnvelopeState_NumbersOnlyGetEnvelopeState_PTGetEnvelopeState_PooledEnvInstance
GetEnvelopeState_VisGetEnvelopeState_Voltype 
Get Envelope
GetAllTrackEnvelopesGetClosestEnvelopePointIDX_ByTimeGetEnvelopePointGetEnvelopePointIDX_Between
GetLastEnvelopePoint_TrackEnvelope  
Helper functions
ActivateEnvelopeCheckEnvelopePointObjectCountEnvelopePointsCreateEnvelopePointObject
GetTrackEnvelope_ClickStateIsValidEnvStateChunkIsValidEnvelopePointArrayIsValidEnvelopePointObject
   
Set Envelope States
SetArmState_EnvelopeSetEnvelopeState_ActSetEnvelopeState_DefShapeSetEnvelopeState_LaneHeight
SetEnvelopeState_Vis  
Set Envelope
AddEnvelopePoints_EnvelopePointArrayAddEnvelopePoints_EnvelopePointObjectDeleteEnvelopePoints_EnvelopePointArrayDeleteEnvelopePoints_EnvelopePointObject
MoveTrackEnvelopePointsBySetEnvelopeHeightSetEnvelopePoints_EnvelopePointArraySetEnvelopePoints_EnvelopePointObject
   

Event Manager

EventManager_AddEventEventManager_AddStartupEventEventManager_CountRegisteredEventsEventManager_CountStartupEvents
EventManager_DebugModeEventManager_DebugMode_UserSpaceEventManager_EnumerateEventsEventManager_EnumerateEvents2
EventManager_EnumerateStartupEventsEventManager_EnumerateStartupEvents2EventManager_GetEventIdentifierEventManager_GetLastCheckfunctionState
EventManager_GetLastCheckfunctionState2EventManager_GetLastUpdateTimeEventManager_GetPausedStateEventManager_GetPausedState2
EventManager_GetRegisteredEventIDEventManager_IsValidEventIdentifierEventManager_PauseEventEventManager_RemoveAllEvents_Script
EventManager_RemoveEventEventManager_RemoveStartupEventEventManager_RemoveStartupEvent2EventManager_ResumeEvent
EventManager_SetEventEventManager_SetStartupEventEventManager_StartEventManager_Stop
   

FX-Management

FXStateChunks
CountFXFromFXStateChunkCountFXStateChunksInStateChunkGetAllRFXChainfilenamesGetFXStateChunk
IsValidFXStateChunkLoadFXStateChunkFromRFXChainFileRemoveFXStateChunkFromItemStateChunkRemoveFXStateChunkFromTrackStateChunk
SaveFXStateChunkAsRFXChainfileSetFXStateChunk 
Get States
GetDocked_FXStateChunkGetFXBypass_FXStateChunkGetFXComment_FXStateChunkGetFXFloatPos_FXStateChunk
GetFXFromFXStateChunkGetFXGuid_FXStateChunkGetFXMidiPreset_FXStateChunkGetFXSettingsString_FXLines
GetFXWak_FXStateChunkGetLastSel_FXStateChunkGetShow_FXStateChunkGetTakeFXComment
GetTakeFX_AlternativeNameGetTrackFXCommentGetTrackFX_AlternativeNameGetWndRect_FXStateChunk
   
Helper functions
GetFocusedFXGetLastTouchedFXGetRecentFX
InputFX
InputFX_AddByNameInputFX_CopyFXInputFX_CopyFXFromTakeFXInputFX_CopyFXFromTrackFX
InputFX_CopyFXToTakeFXInputFX_CopyFXToTrackFXInputFX_DeleteInputFX_EndParamEdit
InputFX_FormatParamValueInputFX_FormatParamValueNormalizedInputFX_GetChainVisibleInputFX_GetComment
InputFX_GetCountInputFX_GetEQInputFX_GetEQBandEnabledInputFX_GetEQParam
InputFX_GetEnabledInputFX_GetFXChainInputFX_GetFXGUIDInputFX_GetFXName
InputFX_GetFloatingWindowInputFX_GetFormattedParamValueInputFX_GetIOSizeInputFX_GetNamedConfigParm
InputFX_GetNumParamsInputFX_GetOfflineInputFX_GetOpenInputFX_GetParam
InputFX_GetParamExInputFX_GetParamNameInputFX_GetParamNormalizedInputFX_GetParameterStepSizes
InputFX_GetPinMappingsInputFX_GetPresetInputFX_GetPresetIndexInputFX_GetUserPresetFilename
InputFX_MoveFXInputFX_MoveFXFromTakeFXInputFX_MoveFXFromTrackFXInputFX_MoveFXToTakeFX
InputFX_MoveFXToTrackFXInputFX_NavigatePresetsInputFX_QueryFirstFXIndexInputFX_SetEQBandEnabled
InputFX_SetEQParamInputFX_SetEnabledInputFX_SetFXChainInputFX_SetOffline
InputFX_SetOpenInputFX_SetParamInputFX_SetParamNormalizedInputFX_SetPinMappings
InputFX_SetPresetInputFX_SetPresetByIndexInputFX_Show
Parameter Mapping Alias
AddParmAlias_FXStateChunkCountParmAlias_FXStateChunkDeleteParmAlias2_FXStateChunkDeleteParmAlias_FXStateChunk
GetAllParmAliasNames_FXStateChunkGetParmAlias2_FXStateChunkGetParmAlias_FXStateChunkGetParmAlias_MediaTrack
SetParmAlias2_FXStateChunkSetParmAlias_FXStateChunk 
Parameter Mapping LFOLearn
AddParmLFOLearn_FXStateChunkCountParmLFOLearn_FXStateChunkDeleteParmLFOLearn_FXStateChunkGetParmLFOLearn_FXStateChunk
GetParmLFOLearn_MediaItemGetParmLFOLearn_MediaTrackSetParmLFOLearn_FXStateChunk
Parameter Mapping Learn
AddParmLearn_FXStateChunkCountParmLearn_FXStateChunkDeleteParmLearn_FXStateChunkGetParmLearn_FXStateChunk
GetParmLearn_MediaItemGetParmLearn_MediaTrackSetParmLearn_FXStateChunk
Parameter Modulation
AddParmMod_ParmModTableCountParmModFromFXStateChunkCreateDefaultParmModTableDeleteParmModFromFXStateChunk
GetParmModTable_FXStateChunkGetParmModulationChunk_FXStateChunkIsValidParmModTableSetParmMod_ParmModTable
   
Plugins
AutoDetectVSTPluginsFolderScanDXPluginsScanVSTPlugins
Set States
SetDocked_FXStateChunkSetFXBypass_FXStateChunkSetFXComment_FXStateChunkSetFXFloatPos_FXStateChunk
SetFXGuid_FXStateChunkSetFXMidiPreset_FXStateChunkSetFXWak_FXStateChunkSetLastSel_FXStateChunk
SetShow_FXStateChunkSetTakeFXCommentSetTakeFX_AlternativeNameSetTrackFXComment
SetTrackFX_AlternativeNameSetWndRect_FXStateChunk 

File Management

Background Copy
CopyFile_AddFileToQueueCopyFile_FlushCopiedFilesCopyFile_GetBufferSizeCopyFile_GetCopiedStatus
CopyFile_GetCurrentlyCopiedFileCopyFile_GetCurrentlyRunningCopyInstancesCopyFile_GetPausedStateCopyFile_GetRemainingFilesToCopy
CopyFile_IsCurrentlyCopyingCopyFile_PauseCopyFile_SetBufferSizeCopyFile_StartCopying
CopyFile_StopCopying  
File Analysis
CheckForValidFileFormatsCountLinesInFileGetLengthOfFileOnlyFilesOfCertainType
   
Helper functions
CountDirectoriesAndFilesInPathCreateValidTempFileDirectoryExistsDirectoryExists2
GetAllDirectoriesInPathGetAllFilenamesInPathGetAllRecursiveFilesAndSubdirectoriesGetPath
GetReaperWorkDirSetReaperWorkDir 
Manipulate Files
MakeCopyOfFileMakeCopyOfFile_Binary 
Misc
BatchConvertFiles  
Read Files
ReadBinaryFileFromPatternReadBinaryFileUntilPatternReadBinaryFile_OffsetReadFileAsLines_Array
ReadFullFileReadLinerangeFromFileReadSubtitles_SRTReadValueFromFile
   
Write Files
SaveSubtitles_SRTWriteValueToFileWriteValueToFile_InsertWriteValueToFile_InsertBinary
WriteValueToFile_ReplaceWriteValueToFile_ReplaceBinary 

Image File Handling

CaptureScreenAreaAsPNGCaptureWindowAsPNGConvertJPG2PNGConvertPNG2JPG
ResizeJPGResizePNG 

Localization

LocalizeLocalize_RefreshFileLocalize_UseFile

MIDI Management

MIDI Editor
OpenItemInMidiEditorZoomHorizontal_MidiEditorZoomVertical_MidiEditor
Notes
MIDI_SendMidiCCMIDI_SendMidiNoteMIDI_SendMidiPCMIDI_SendMidiPitch
QueryMIDIMessageNameByID  

Manipulate Files

MoveFileOrFolder  

Markers

Assistance functions
CountMarkersAndRegionsGetGuidFromMarkerIDGetMarkerByScreenCoordinatesGetMarkerByTime
GetMarkerIDFromGuidGetMarkerUpdateCounterGetNextFreeRegionIndexGetRegionByScreenCoordinates
GetRegionByTimeGetTimeSignaturesByScreenCoordinatesGetTimeSignaturesByTimeIsMarkerAtPosition
IsRegionAtPositionMoveMarkersByMoveRegionsByParseMarkerString
RenumerateMarkers  
Custom Markers
AddCustomMarkerAddCustomRegionCountAllCustomMarkersCountAllCustomRegions
DeleteCustomMarkersDeleteCustomRegionsEnumerateCustomMarkersEnumerateCustomRegions
GetAllCustomMarkerNamesGetAllCustomMarkersGetAllCustomRegionNamesGetAllCustomRegions
IsMarkerValidCustomMarkerIsRegionValidCustomRegionSetCustomMarkerSetCustomRegion
   
Edit Markers and Regions
AddEditMarkerAddEditRegionCountEditMarkersCountEditRegions
DeleteEditMarkerDeleteEditRegionEditToMarkerEnumerateEditMarkers
EnumerateEditRegionExportEditMarkersToFileGetAllEditMarkersImportEditFromFile
IsMarkerEditIsRegionEditRegionMarkerToEditMarkerSetEditMarker
SetEditRegion  
General Markers and Regions
GetAllMarkersGetAllMarkersBetweenGetAllRegionsGetAllRegionsBetween
GetLastMarkerPositionGetLastRegionGetMarkerAndRegionsByIndexGetMarkerByName
GetMarkerByName_PatternImportMarkersFromFileRippleCut_RegionsSetMarkerByIndex
   
Normal Markers
AddNormalMarkerCountNormalMarkersCountNormalMarkers_NumGapDeleteNormalMarker
EnumerateNormalMarkersExportNormalMarkersToFileGetAllNormalMarkersIsMarkerNormal
SetNormalMarker  
PodRange Region
AddPodRangeRegionDeletePodRangeRegionGetPodRangeRegionIsRegionPodrange
SetPodRangeRegion  
Time Signature Markers
GetAllTimeSigMarkersGetLastTimeSigMarkerPositionIsTimeSigmarkerAtPositionMoveTimeSigMarkersBy
   

Media Explorer

MediaExplorer_OnCommandUpdateMediaExplorer 

MediaItem Management

Assistance functions
ApplyActionToMediaItemApplyActionToMediaItemArrayApplyActionToMediaItemArray2ApplyActionToMediaItemTake
ApplyFunctionToMediaItemArrayCheckMediaItemArrayCheckMediaItemStateChunkArrayCopyMediaItemToDestinationTrack
GetAllMediaItemAttributes_TableGetAllMediaItemGUIDsGetEndOfItemGetGapsBetweenItems
GetItem_ClickStateGetItem_HighestRecCounterGetItem_NumberGetMediaItemArrayLength
GetMediaItemStateChunkArrayLengthGetMediaItemStateChunksFromItemsGetMediaItemStateChunksFromMediaItemArrayGetMediafileAttributes
GetParentTrack_MediaItemIsItemInTimerangeIsItemVisibleIsSplitAtPosition
IsValidMediaItemArrayIsValidMediaItemStateChunkIsValidMediaItemStateChunkArrayOnlyItemsInTracksAndTimerange
OnlyMediaItemsOfTracksInTrackstringOnlyMediaItemsOfTracksInTrackstring_StateChunkPreviewMediaFilePreviewMediaItem
SetAllMediaItemAttributes_TableStopAnyPreview 
Delete
DeleteMediaItemDeleteMediaItemsFromArrayDeleteMediaItems_PositionDeleteMediaItems_Position
   
Edit
RippleCutRippleCut_ReverseSectionCutSectionCut_Inverse
SplitItemsAtPositionFromArraySplitMediaItems_Position 
Get MediaItem States
GetItemAllTakesGetItemBeatGetItemChanModeGetItemFadeFlag
GetItemFadeInGetItemFadeOutGetItemGUIDGetItemGroup
GetItemIGUIDGetItemIIDGetItemImageGetItemLength
GetItemLockGetItemLoopGetItemMixFlagGetItemMute
GetItemNameGetItemPlayRateGetItemPositionGetItemRecPass
GetItemSampleOffsetGetItemSelectedGetItemSnapOffsetGetItemStateChunk
GetItemUSTrackNumber_StateChunkGetItemVolPanGetItem_Video_IgnoreAudio
Get MediaItems
EnumerateMediaItemsInTrackGetAllLockedItemsFromMediaItemArrayGetAllMediaItemsGetAllMediaItemsBetween
GetAllMediaItemsFromTrackGetAllMediaItemsInTimeSelectionGetAllSelectedMediaItemsBetweenGetMediaItemsAtPosition
   
Insert
InsertImageFileInsertMediaItemArrayInsertMediaItemFromFileInsertMediaItemStateChunkArray
InsertMediaItem_MediaItemInsertMediaItem_MediaItemStateChunkRippleInsertRippleInsert_MediaItemStateChunks
   
Manipulate
AddLockStateToMediaItemStateChunkAddLockStateTo_MediaItemStateChunkArrayApplyStateChunkToItemsChangeDeltaLengthOfMediaItems_FromArray
ChangeDeltaOffsetOfMediaItems_FromArrayChangeLengthOfMediaItems_FromArrayChangeOffsetOfMediaItems_FromArrayMoveMediaItemsAfter_By
MoveMediaItemsBefore_ByMoveMediaItemsBetween_ToMoveMediaItems_FromArrayNormalizeItems
SetItemsLockState  
MediaItem-Takes
CountMediaItemTake_StateChunkGetItemSourceFile_TakeGetMediaItemTakeGetMediaItemTake_StateChunk
GetTake_ReverseState  
Outtakes Vault
MediaItems_Outtakes_AddSelectedItemsMediaItems_Outtakes_GetAllItemsMediaItems_Outtakes_InsertAllItems
Selected Items
DeselectMediaItems_MediaItemArrayGetAllSelectedMediaItemsGetSelectedMediaItemsAtPositionGetSelectedMediaItemsBetween
SelectMediaItems_MediaItemArraySetMediaItemsSelected_TimeSelection 
Set MediaItem States
SetItemImageSetItemLengthSetItemPositionSetItemUSTrackNumber_StateChunk
SetItem_Video_IgnoreAudioSetMediaItemStateChunk_in_TrackStateChunk 
Spectral Edit
AddItemSpectralEditCountItemSpectralEditsDeleteItemSpectralEditGetItemSpectralConfig
GetItemSpectralConfig2GetItemSpectralConfig2GetItemSpectralEditGetItemSpectralEdit2
GetItemSpectralVisibilityStateSetItemSpectralConfigSetItemSpectralEditSetItemSpectralVisibilityState
   

Metadata Management

Extension States(Guid)
GetGuidExtStateSetGuidExtState 
Extension States
DeleteProjExtState_KeyDeleteProjExtState_SectionGetProjExtState_AllKeyValuesProjExtState_CountAllKeys
   
Markers
GetMarkerExtStateSetMarkerExtState 
Reaper Metadata Management
Metadata_GetAllPresetNamesMetadata_GetMetaDataTable_Presets 
Tags
Metadata_AIFF_GetSetMetadata_APE_GetSetMetadata_BWF_GetSetMetadata_CART_GetSet
Metadata_CUE_GetSetMetadata_ID3_GetSetMetadata_INFO_GetSetMetadata_IXML_GetSet
Metadata_VORBIS_GetSetMetadata_XMP_GetSet 

Miscellaneous

WinterlySnowflakes  

Mute Management

Mute Lane
ActivateMuteActivateMute_TrackObjectDeactivateMuteDeactivateMute_TrackObject
   
Muting tracks within envelope-lanes
CountMuteEnvelopePointsDeleteMuteStateDeleteMuteState_TrackObjectGetNextMuteState
GetNextMuteState_TrackObjectGetPreviousMuteStateGetPreviousMuteState_TrackObjectIsMuteAtPosition
IsMuteAtPosition_TrackObjectToggleMuteToggleMute_TrackObject

Navigation

CenterViewToCursorGetClosestGoToPointsGetClosestNextMarkerGetClosestNextRegionEdge
GetClosestPreviousMarkerGetClosestPreviousRegionEdgeGetLastCursorPositionGetLastLoopState
GetLastPlayStateGetNextClosestItemEdgeGetPreviousClosestItemEdgeJumpBackwardBy
JumpBackwardBy_RecordingJumpForwardByJumpForwardBy_RecordingSetPlayAndEditCursor_WhenPlaying
SetPlayCursor_WhenPlayingToggleScrollingDuringPlayback 
Scrubbing
Scrubbing_MoveCursor_GetToggleStateScrubbing_MoveCursor_Toggle 
Transport
GetLoopStateSetLoopState 

Project-Files

Helper functions
GetProjectStateChunk  
RPP-Files Set
SetProject_GroupOverride  

Project-Management

AutoSave
AutoSave_GetMinutesAutoSave_GetOptionsAutoSave_SetMinutesAutoSave_SetOptions
   
Helper functions
CheckForChangedProjectTabsConvertOldProjectToCurrentReaperVersionCountProjectTabsCreateTemporaryFileOfProjectfile
EnumProjectsGetCurrentTimeLengthOfFrameGetLengthOfFramesGetProjectFilename
GetProjectLengthGetProject_LengthGetProject_LengthGetProject_Tabs
GetRecentProjectsIsTimeSelectionActiveIsValidProjectStateChunkIsValidReaProject
NewProjectTab  
ProjectBay
GetAllMediaItems_FromProjectBayStateChunkIsValidProjectBayStateChunk 
RPP-Files Get
GetProjectState_NumbersOnlyGetProject_AddMediaToProjectAfterRenderGetProject_ApplyFXCFGGetProject_Author
GetProject_AutoCrossFadeGetProject_CountMarkersAndRegionsGetProject_CountMasterHWOutsGetProject_CursorPos
GetProject_DefPitchModeGetProject_EnvAttachGetProject_ExtensionsGetProject_Feedback
GetProject_GetMarkerGetProject_GetRegionGetProject_GlobalAutoGetProject_Grid
GetProject_GroupDisabledGetProject_GroupNameGetProject_GroupOverrideGetProject_HorizontalZoom
GetProject_ItemMixBehaviorGetProject_LockGetProject_LoopGetProject_LoopGran
GetProject_MarkersAndRegionsGetProject_MasterAutomodeGetProject_MasterDualPanEnv2StateChunkGetProject_MasterDualPanEnvL2StateChunk
GetProject_MasterDualPanEnvLStateChunkGetProject_MasterDualPanEnvStateChunkGetProject_MasterFXBypGetProject_MasterFXListStateChunk
GetProject_MasterGroupFlagsHighStateGetProject_MasterGroupFlagsStateGetProject_MasterHWOutGetProject_MasterHWPanEnvStateChunk
GetProject_MasterHWVolEnvStateChunkGetProject_MasterMuteSoloGetProject_MasterNChansGetProject_MasterPanMode
GetProject_MasterPanMode_ExGetProject_MasterPlayspeedGetProject_MasterSelGetProject_MasterTrackColor
GetProject_MasterTrackHeightGetProject_MasterTrackViewGetProject_MasterVolEnv2StateChunkGetProject_MasterVolEnv3StateChunk
GetProject_MasterVolEnvStateChunkGetProject_MasterVolumeGetProject_MasterWidthGetProject_MaxProjectLength
GetProject_MetaDataStateChunkGetProject_MetronomeGetProject_MixerUIFlagsGetProject_NumberOfTracks
GetProject_PanLawGetProject_PanModeGetProject_PeakGainGetProject_Playrate
GetProject_PooledEnvAttachGetProject_ProjOffsetsGetProject_ProjectBayGetProject_QRenderOriginalProject
GetProject_QRenderOutFilesGetProject_ReaperVersionGetProject_RecModeGetProject_RecPath
GetProject_RecordCFGGetProject_RenderCFGGetProject_RenderDitherStateGetProject_RenderFilename
GetProject_RenderFreqNChansGetProject_RenderPatternGetProject_RenderQueueDelayGetProject_RenderRange
GetProject_RenderResampleGetProject_RenderSpeedGetProject_RenderStemsGetProject_RippleState
GetProject_SMPTESyncGetProject_SampleRateGetProject_SelectionGetProject_TakeLane
GetProject_TempoGetProject_TempoEnvExGetProject_TempoEnv_ExStateChunkGetProject_TempoTimeSignature
GetProject_TimeBaseGetProject_TimemodeGetProject_TrackMixingDepthGetProject_TrackStateChunk
GetProject_UseRecConfigGetProject_VerticalZoomGetProject_VideoConfig
RPP-Files Set
SetProject_AddMediaToProjectAfterRenderSetProject_ApplyFXCFGSetProject_AutoCrossFadeSetProject_CursorPos
SetProject_DefPitchModeSetProject_EnvAttachSetProject_FeedbackSetProject_GlobalAuto
SetProject_GridSetProject_HorizontalZoomSetProject_ItemMixBehaviorSetProject_Lock
SetProject_LoopSetProject_LoopGranSetProject_MasterAutomodeSetProject_MasterFXByp
SetProject_MasterMuteSoloSetProject_MasterNChansSetProject_MasterPanModeSetProject_MasterSel
SetProject_MasterTrackColorSetProject_MasterTrackHeightSetProject_MasterTrackViewSetProject_MaxProjectLength
SetProject_MixerUIFlagsSetProject_PanLawSetProject_PanModeSetProject_PeakGain
SetProject_PlayrateSetProject_ProjOffsetsSetProject_RecModeSetProject_RecPath
SetProject_RecordCFGSetProject_RenderCFGSetProject_RenderDitherStateSetProject_RenderFilename
SetProject_RenderFreqNChansSetProject_RenderPatternSetProject_RenderQueueDelaySetProject_RenderRange
SetProject_RenderResampleSetProject_RenderSpeedSetProject_RenderStemsSetProject_RippleState
SetProject_SMPTESyncSetProject_SampleRateSetProject_SelectionSetProject_TakeLane
SetProject_TempoSetProject_TempoTimeSignatureSetProject_TimeBaseSetProject_Timemode
SetProject_TrackMixingDepthSetProject_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_VideoGetRenderCFG_Settings_AudioCD
GetRenderCFG_Settings_DDPGetRenderCFG_Settings_FLACGetRenderCFG_Settings_GIFGetRenderCFG_Settings_LCF
GetRenderCFG_Settings_M4AMacGetRenderCFG_Settings_MKV_VideoGetRenderCFG_Settings_MOVMac_VideoGetRenderCFG_Settings_MP3
GetRenderCFG_Settings_MP3ABRGetRenderCFG_Settings_MP3CBRGetRenderCFG_Settings_MP3MaxQualityGetRenderCFG_Settings_MP3VBR
GetRenderCFG_Settings_MP4Mac_VideoGetRenderCFG_Settings_OGGGetRenderCFG_Settings_OPUSGetRenderCFG_Settings_QTMOVMP4_Video
GetRenderCFG_Settings_WAVGetRenderCFG_Settings_WAVPACKGetRenderCFG_Settings_WebMVideo
Assistance functions
ApplyRenderTable_ProjectApplyRenderTable_ProjectFileAreRenderTablesEqualCreateNewRenderTable
GetLastRenderPathsGetLastUsedRenderPatternsGetRenderTable_ProjectGetRenderTable_ProjectFile
IsReaperRenderingIsValidRenderTable 
Creating Renderstrings
CreateRenderCFG_AIFFCreateRenderCFG_AVI_VideoCreateRenderCFG_AudioCDCreateRenderCFG_DDP
CreateRenderCFG_FLACCreateRenderCFG_GIFCreateRenderCFG_LCFCreateRenderCFG_M4AMAC
CreateRenderCFG_MKV_VideoCreateRenderCFG_MOVMAC_VideoCreateRenderCFG_MP3ABRCreateRenderCFG_MP3CBR
CreateRenderCFG_MP3MaxQualityCreateRenderCFG_MP3VBRCreateRenderCFG_MP4MAC_VideoCreateRenderCFG_OGG
CreateRenderCFG_OpusCreateRenderCFG_QTMOVMP4_VideoCreateRenderCFG_WAVCreateRenderCFG_WAVPACK
CreateRenderCFG_WebMVideo  
Render Presets
AddRenderPresetDeleteRenderPreset_BoundsDeleteRenderPreset_FormatOptionsGetRenderPreset_Names
GetRenderPreset_RenderTableSetRenderPreset 
Render Settings
GetRender_AddRenderedFilesToProjectGetRender_AutoIncrementFilenameGetRender_EmbedMetaDataGetRender_EmbedStretchMarkers
GetRender_NoSilentFilesGetRender_OfflineOnlineModeGetRender_ProjectSampleRateForMixGetRender_QueueDelay
GetRender_ResampleModeGetRender_SaveCopyOfProjectGetRender_TailLengthSetRender_AddRenderedFilesToProject
SetRender_AutoIncrementFilenameSetRender_EmbedMetaDataSetRender_EmbedStretchMarkersSetRender_NoSilentFiles
SetRender_OfflineOnlineModeSetRender_ProjectSampleRateForMixSetRender_QueueDelaySetRender_ResampleMode
SetRender_SaveCopyOfProjectSetRender_TailLength 
RenderQueue
AddProjectFileToRenderQueueAddSelectedItemsToRenderQueueGetRenderQueuedProjectsRenderProject_RenderQueue
   
Rendering any Outputformat
RenderProjectRenderProject_RegionsRenderProject_RenderTableRender_Loop
   

Themeing

ApplyAllThemeLayoutParametersGetAllThemeLayoutNamesGetAllThemeLayoutParametersGetThemeParameterIndexByDescription
GetThemeParameterIndexByNameSetThemeParameterIndexByDescriptionSetThemeParameterIndexByName
Default v6-Theme
Theme_Defaultv6_GetEnvFaderSizeTheme_Defaultv6_GetEnvFolderIndentTheme_Defaultv6_GetEnvNameSizeTheme_Defaultv6_GetEnvSize
Theme_Defaultv6_GetHideTCPElementTheme_Defaultv6_GetMCPAlignControlsTheme_Defaultv6_GetMCPBorderStyleTheme_Defaultv6_GetMCPFolderIndent
Theme_Defaultv6_GetMCPMeterExpansionTheme_Defaultv6_GetMCPSizeAndLayoutTheme_Defaultv6_GetStyleMCPElementTheme_Defaultv6_GetTCPAlignControls
Theme_Defaultv6_GetTCPFolderIndentTheme_Defaultv6_GetTCPInputSizeTheme_Defaultv6_GetTCPMeterLocationTheme_Defaultv6_GetTCPMeterSize
Theme_Defaultv6_GetTCPNameSizeTheme_Defaultv6_GetTCPSizeAndLayoutTheme_Defaultv6_GetTCPVolumeSizeTheme_Defaultv6_GetTransPlayRateSize
Theme_Defaultv6_GetTransSizeTheme_Defaultv6_SetEnvFaderSizeTheme_Defaultv6_SetEnvFolderIndentTheme_Defaultv6_SetEnvNameSize
Theme_Defaultv6_SetEnvSizeTheme_Defaultv6_SetHideTCPElementTheme_Defaultv6_SetMCPAlignControlsTheme_Defaultv6_SetMCPBorderStyle
Theme_Defaultv6_SetMCPFolderIndentTheme_Defaultv6_SetMCPMeterExpansionTheme_Defaultv6_SetMCPSizeAndLayoutTheme_Defaultv6_SetStyleMCPElement
Theme_Defaultv6_SetTCPAlignControlsTheme_Defaultv6_SetTCPFolderIndentTheme_Defaultv6_SetTCPInputSizeTheme_Defaultv6_SetTCPMeterLocation
Theme_Defaultv6_SetTCPMeterSizeTheme_Defaultv6_SetTCPNameSizeTheme_Defaultv6_SetTCPSizeAndLayoutTheme_Defaultv6_SetTCPVolumeSize
Theme_Defaultv6_SetTransPlayRateSizeTheme_Defaultv6_SetTransSize 

Track Management

Assistance functions
AddMediaItemStateChunk_To_TrackStateChunkAnyTrackFXBypassAnyTrackFreeItemPositioningModeAnyTrackHiddenMCP
AnyTrackHiddenTCPAnyTrackMuteAnyTrackPhasedAnyTrackRecMonitored
AnyTrackRecarmedApplyActionToTrackCountItemsInTrackStateChunkCreateTrackString
CreateTrackStringByGUIDCreateTrackStringByMediaTracksCreateTrackStringByTracknamesCreateTrackString_AllTracks
CreateTrackString_ArmedTracksCreateTrackString_SelectedTracksCreateTrackString_UnarmedTracksDeleteTracks_TrackString
GetAllMediaItemsFromTrackStateChunkGetAllVisibleTracks_ArrangeGetItemStateChunkFromTrackStateChunkGetLengthOfAllMediaItems_Track
GetTrackLengthGetTracknumberByGuidInsertTrackAtIndexInsertTrack_TrackStateChunk
InverseTrackstringIsTrackObjectTracknumberIsTrackVisibleIsValidTrackStateChunk
IsValidTrackStringMoveTracksOnlyTracksInBothTrackstringsOnlyTracksInOneTrackstring
RemoveDuplicateTracksInTrackstringRemoveMediaItemByGUID_TrackStateChunkRemoveMediaItemByIGUID_TrackStateChunkRemoveMediaItem_TrackStateChunk
   
Get Track States
GetAllLockedTracksGetAllSelectedTracksGetTrackAutoRecArmStateGetTrackAutomodeState
GetTrackBeatStateGetTrackBusCompStateGetTrackBypFXStateGetTrackFreeModeState
GetTrackGroupFlagsStateGetTrackGroupFlags_HighStateGetTrackHeightStateGetTrackID
GetTrackINQStateGetTrackIPhaseStateGetTrackIcon_FilenameGetTrackIsBusState
GetTrackLayoutNamesGetTrackLockStateGetTrackMIDIOutStateGetTrackMainSendState
GetTrackMidiBankProgFnGetTrackMidiCTLGetTrackMidiColorMapFnGetTrackMidiInputChanMap
GetTrackMidiTextStrFnGetTrackMuteSoloStateGetTrackNChansStateGetTrackName
GetTrackPanModeGetTrackPeakColorStateGetTrackPerfStateGetTrackRecCFG
GetTrackRecStateGetTrackScoreGetTrackSelection_TrackStateChunkGetTrackShowInMixState
GetTrackStateChunk_TracknumberGetTrackState_NumbersOnlyGetTrackVUStateGetTrackVolPan
GetTrackWidthSetTrackSelection_TrackStateChunk 
Hardware Out
AddTrackHWOutApplyAllHWOutsAreHWOutsTablesEqualClearRoutingMatrix
CountTrackHWOutsDeleteTrackHWOutGetAllHWOutsGetTrackHWOut
SetTrackHWOut  
Send/Receive-Routing
AddTrackAUXSendReceivesApplyAllAUXSendReceivesApplyAllMainSendStatesAreAUXSendReceivesTablesEqual
AreMainSendsTablesEqualClearRoutingMatrixCountTrackAUXSendReceivesDeleteTrackAUXSendReceives
GetAllAUXSendReceivesGetAllMainSendStatesGetTrackAUXSendReceivesSetTrackAUXSendReceives
   
Set Track States
CollapseTrackHeightGetTrackByTrackNameSetAllTracksSelectedSetTrackAutoRecArmState
SetTrackAutomodeStateSetTrackBeatStateSetTrackBusCompStateSetTrackBypFXState
SetTrackFreeModeStateSetTrackGroupFlagsStateSetTrackGroupFlags_HighStateSetTrackHeightState
SetTrackIDSetTrackINQStateSetTrackIPhaseStateSetTrackIcon_Filename
SetTrackIsBusStateSetTrackLayoutNamesSetTrackLockStateSetTrackMIDIOutState
SetTrackMainSendStateSetTrackMidiBankProgFnSetTrackMidiCTLSetTrackMidiColorMapFn
SetTrackMidiInputChanMapSetTrackMidiTextStrFnSetTrackMuteSoloStateSetTrackNChansState
SetTrackNameSetTrackPanModeSetTrackPeakColorStateSetTrackPerfState
SetTrackRecCFGSetTrackRecStateSetTrackScoreSetTrackShowInMixState
SetTrackStateChunk_TracknumberSetTrackVUStateSetTrackVolPanSetTrackWidth
SetTrack_LastTouchedSetTrack_Trackheight_ForceSetTracksSelectedSetTracksToLocked
SetTracksToUnlocked  

TrackManager

TrackManager_ClearFilterTrackManager_OpenCloseTrackManager_SelectionFromListTrackManager_SelectionFromProject
TrackManager_SetFilterTrackManager_ShowAll 

Ultraschall Specific

Followmode
pause_follow_one_cycle  
Routing
GetAllAUXSendReceives2GetAllHWOuts2GetAllMainSendStates2
Soundboard
SoundBoard_PlaySoundBoard_PlayList_CurrentIndexSoundBoard_PlayList_NextSoundBoard_PlayList_Previous
SoundBoard_PlayList_SetIndexSoundBoard_StopSoundBoard_StopAllSoundsSoundBoard_TogglePlayPause
SoundBoard_TogglePlayStopSoundBoard_TogglePlay_FadeOutStopSoundboard_PlayFadeIn
Track Management
GetTypeOfTrackIsTrackSoundboardIsTrackStudioLinkIsTrackStudioLinkOnAir
   
Ultraschall.ini
CountUSExternalState_keyCountUSExternalState_secDeleteUSExternalStateEnumerateUSExternalState_key
EnumerateUSExternalState_secGetUSExternalStateSetUSExternalState

User Interface

GetPreventUIRefreshCountPreventUIRefreshRestoreUIRefresh
Arrangeview Management
DeleteArrangeviewSnapshotGetVerticalScrollGetVerticalZoomIsValidArrangeviewSnapshot
RestoreArrangeviewSnapshotRetrieveArrangeviewSnapshotSetVerticalRelativeScrollSetVerticalScroll
SetVerticalZoomStoreArrangeviewSnapshot 
Context Menus
ShowMenu  
Dialogs
BrowseForOpenFilesGetUserInputsMB
MediaItems
GetItemButtonsVisibleSetItemButtonsVisible 
Menu Management
ShowAutomationItemMenuShowEnvelopeMenuShowEnvelopePointMenuShowEnvelopePointMenu_AutomationItem
ShowMediaItemMenuShowRulerMenuShowTrackAreaMenuShowTrackInputMenu
ShowTrackPanelMenuShowTrackRoutingMenu 
Miscellaneous
ConvertYCoordsMac2WinGetIDEFontSizeGetTimeByMouseXPositionGetUIScale
SetIDEFontSizeSetUIScale 
Reaper-Windowhandler
GetActionsHWNDGetBatchFileItemConverterHWNDGetConsolidateTracksHWNDGetExportProjectMIDIHWND
GetHWND_ArrangeViewAndTimeLineGetMediaExplorerHWNDGetPreferencesHWNDGetProjectDirectoryCleanupHWND
GetProjectSettingsHWNDGetReaScriptConsoleWindowGetRenderQueueHWNDGetRenderToFileHWND
GetRenderingToFileHWNDGetSaveLiveOutputToDiskHWNDGetSaveProjectAsHWNDGetTrackManagerHWND
GetVideoHWND  
Screen Management
GetScreenHeightGetScreenWidth 
Track Control Panel(TCP)
GetTCPWidthTCP_SetWidth 
Transport and Ruler
SetTimeUnit  
Transport
GetPlayCursorWidthSetPlayCursorWidth 
UI-Elements
GetCheckboxStateSetCheckboxState 
Window Management
CloseReaScriptConsoleGetAllReaScriptIDEWindowsGetChildSizeWithinParentHWNDGetReaperWindowAttributes
GetTopmostHWNDHasHWNDChildWindowNamesIsValidHWNDMoveChildWithinParentHWND
ReturnAllChildHWNDVideoWindow_FullScreenToggleWindows_Find
misc
GetHelpDisplayModeSetHelpDisplayModeWiringDiagram_GetOptionsWiringDiagram_SetOptions
   

Web Interface

WebInterface_GetInstalledInterfaces  


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ CountProjectTabs

Functioncall:

integer number_of_projecttabs = ultraschall.CountProjectTabs()

Description:
Counts the number of opened project tabs.

Returnvalues:
 integer number_of_projecttabs the number of projecttabs currently opened 



^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ GetProject_Tabs

Functioncall:

integer number_of_projecttabs, array projecttablist = ultraschall.GetProject_Tabs()

Description:
Returns the ReaProject-objects, as well as the filenames of all opened project-tabs.

Returnvalues:
 integer number_of_projecttabs the number of projecttabs currently opened 
 array projecttablist an array, that holds all ReaProjects as well as the projectfilenames
projecttablist[idx][1] = ReaProject
projecttablist[idx][2] = projectfilename with path 



^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ GetApiVersion

Functioncall:

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

Description:
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 5.965Ultraschall version 4.00Lua version 5.3 ^ SuppressErrorMessages

Functioncall:

boolean retval = ultraschall.SuppressErrorMessages(boolean flag)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ AddErrorMessage

Functioncall:

boolean retval, integer errorcount = ultraschall.AddErrorMessage(string functionname, string parametername, string errormessage, integer errorcode)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ StartTime

Functioncall:

ultraschall.StartTime

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ API_TempPath

Functioncall:

ultraschall.API_TempPath

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




^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ Euro

Functioncall:

ultraschall.Euro

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




^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ApiTest

Functioncall:

ultraschall.ApiTest()

Description:
Displays a message to show, which parts of the Ultraschall-API are turned on and which are turned off.




^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ToggleIDE_Errormessages

Functioncall:

boolean retval = ultraschall.ToggleIDE_Errormessages(optional boolean togglevalue)

Description:
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.40Ultraschall version 4.1Lua version 5.3 ^ ReadErrorMessage

Functioncall:

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)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ DeleteErrorMessage

Functioncall:

boolean retval = ultraschall.DeleteErrorMessage(integer errornumber)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetLastErrorMessage

Functioncall:

boolean retval, integer errcode, string functionname, string parmname, string errormessage, string lastreadtime, string err_creation_date, string err_creation_timestamp, integer errorcounter = ultraschall.GetLastErrorMessage()

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ DeleteLastErrorMessage

Functioncall:

boolean retval = ultraschall.DeleteLastErrorMessage()

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ DeleteAllErrorMessages

Functioncall:

boolean retval = ultraschall.DeleteAllErrorMessages()

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetLastErrorMessage2

Functioncall:

boolean retval, array ErrorMessages = ultraschall.GetLastErrorMessage2(integer count, boolean setread)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountErrorMessages

Functioncall:

integer errorcounter = ultraschall.CountErrorMessages()

Description:
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.40Ultraschall version 4.1Lua version 5.3 ^ ShowLastErrorMessage

Functioncall:

requested_error_message = ultraschall.ShowLastErrorMessage(optional integer dunk, optional integer target, optional integer message_type)

Description:
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.40Ultraschall version 4.1Lua version 5.3 ^ SLEM

Functioncall:

requested_error_message = SLEM(optional integer dunk, optional integer target, optional integer message_type)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ Separator

Functioncall:

ultraschall.Separator

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ Api_Path

Functioncall:

ultraschall.Api_Path

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




^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ Api_InstallPath

Functioncall:

ultraschall.Api_InstallPath

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




^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ GetLastErrorMessage_Funcname

Functioncall:

integer errorindex, string parametername, string errormessage, integer errorcode = ultraschall.GetLastErrorMessage_Funcname(string functionname)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ CountErrorMessage_Funcname

Functioncall:

integer number_of_errormessages = ultraschall.CountErrorMessage_Funcname(string functionname)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ GetErrorMessage_Funcname

Functioncall:

integer errorindex, string parametername, string errormessage, integer errorcode = ultraschall.GetErrorMessage_Funcname(string functionname, integer index)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ ShowErrorMessagesInReascriptConsole

Functioncall:

ultraschall.ShowErrorMessagesInReascriptConsole(boolean state)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ WinterlySnowflakes

Functioncall:

integer retval = ultraschall.WinterlySnowflakes(boolean toggle, number falling_speed, integer number_snowflakes)

Description:
Exchanges the gfx.update()-function with a variant, that displays falling snowflakes everytime it is called.

returns -1 in case of error

Returnvalues:
 integer retval returns -1 in case of a'JS_Window_ListFind' n error; 1, in case of success 

Parameters:
 boolean toggle true, toggles falling snow on; false, toggles falling snow off 
 number falling_speed the falling speed of the snowflakes, 1.3 is recommended 
 integer number_snowflakes the number of falling snowflakes at the same time on screen; 2000 is recommended 


^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ PingMe

Functioncall:

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

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ print2

Functioncall:

print2(parameter_1 to parameter_n)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ print_alt

Functioncall:

print_alt(parameter_1 to parameter_n)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ print

Functioncall:

print(parameter_1 to parameter_n)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ toboolean

Functioncall:

boolean retval = toboolean(string value)

Description:
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.965Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ print3

Functioncall:

print(parameter_1 to parameter_n)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ print_update

Functioncall:

print_update(parameter_1 to parameter_n)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CheckActionCommandIDFormat

Functioncall:

boolean retval = ultraschall.CheckActionCommandIDFormat(action_command_id)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ RunCommand

Functioncall:

integer retval = ultraschall.RunCommand(string actioncommand_id)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ ConvertStringToBits

Functioncall:

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

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ ConvertBitsToString

Functioncall:

string message = ultraschall.ConvertBitsToString(array bitarray)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ deprecated

Functioncall:

ultraschall.deprecated(string functionname)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ FloatCompare

Functioncall:

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

Description:
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 6.02Ultraschall version 4.00SWS version 2.10.0.1Lua version 5.3 ^ ToClip

Functioncall:

ToClip(string toclipstring)

Description:
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 6.02Ultraschall version 4.00SWS version 2.10.0.1Lua version 5.3 ^ FromClip

Functioncall:

string clipboard_string = FromClip()

Description:
Gets a string from clipboard.

Returnvalues:
 string clipboard_string the string-content from the clipboard 



^ Reaper version 6.05Ultraschall version 4.1Lua version 5.3 ^ EscapeMagicCharacters_String

Functioncall:

string escaped_string = ultraschall.EscapeMagicCharacters_String(string sourcestring)

Description:
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 6.05Ultraschall version 4.1SWS version 2.10.0.1Julian Sader's plugin version 0.963Lua version 5.3 ^ ActionsList_GetSelectedActions

Functioncall:

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

Description:
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 6.02Ultraschall version 4.1Lua version 5.3 ^ Gmem_GetCurrentAttachedName

Functioncall:

string current_gmem_attachname = ultraschall.Gmem_GetCurrentAttachedName()

Description:
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 6.05Ultraschall version 4.1SWS version 2.10.0.1Julian Sader's plugin version 0.963Lua version 5.3 ^ ActionsList_GetAllActions

Functioncall:

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

Description:
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.02Ultraschall version 4.1Lua version 5.3 ^ BringReaScriptConsoleToFront

Functioncall:

ultraschall.BringReaScriptConsoleToFront()

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




^ Reaper version 6.10Ultraschall version 4.2Lua version 5.3 ^ EditReaScript

Functioncall:

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)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ SFEM

Functioncall:

requested_error_message = SFEM(optional integer dunk, optional integer target, optional integer message_type)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ RFR

Functioncall:

... = RFR(integer length, ...)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ RLR

Functioncall:

... = RLR(integer length, ...)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ RRR

Functioncall:

... = RRR(integer position, integer length, ...)

Description:
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 5.965Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetHWInputs_Aliasnames

Functioncall:

integer number_of_aliases, table aliases = ultraschall.GetHWInputs_Aliasnames()

Description:
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.965Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetHWOutputs_Aliasnames

Functioncall:

integer number_of_aliases, table aliases = ultraschall.GetHWOutputs_Aliasnames()

Description:
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 5.95Ultraschall version 4.00Lua version 5.3 ^ GetProject_AutomationItemStateChunk

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ GetProject_CountAutomationItems

Functioncall:

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

Description:
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.05Ultraschall version 4.1Lua version 5.3 ^ AutomationItems_GetAll

Functioncall:

integer number_of_automationitems, table AutomationItems_Table = ultraschall.AutomationItems_GetAll()

Description:
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.05Ultraschall version 4.2Lua version 5.3 ^ AutomationItem_Delete

Functioncall:

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

Description:
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.10Ultraschall version 4.2Lua version 5.3 ^ AutomationItems_GetByTime

Functioncall:

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

Description:
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 6.10Ultraschall version 4.2Lua version 5.3 ^ AutomationItem_Split

Functioncall:

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

Description:
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 5.40Ultraschall version 4.00Lua version 5.3 ^ GetMediaItemsFromClipboard

Functioncall:

integer count, array MediaItemStateChunkArray = ultraschall.GetMediaItemsFromClipboard()

Description:
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.52Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetStringFromClipboard_SWS

Functioncall:

string clipboard_string = ultraschall.GetStringFromClipboard_SWS()

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ PutMediaItemsToClipboard_MediaItemArray

Functioncall:

boolean retval = ultraschall.PutMediaItemsToClipboard_MediaItemArray(MediaItemArray MediaItemArray)

Description:
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 5.52Ultraschall version 4.00Lua version 5.3 ^ ConvertColor

Functioncall:

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

Description:
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.52Ultraschall version 4.00Lua version 5.3 ^ ConvertColorReverse

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ RGB2Grayscale

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ ConvertColorToGFX

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ ConvertGFXToColor

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ CreateColorTable

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ CreateSonicRainboomColorTable

Functioncall:

array ColorTable = ultraschall.CreateSonicRainboomColorTable()

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ IsValidColorTable

Functioncall:

boolean retval = ultraschall.IsValidColorTable(array ColorTable)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ApplyColorTableToTrackColors

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ApplyColorTableToItemColors

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ChangeColorBrightness

Functioncall:

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)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ChangeColorContrast

Functioncall:

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)

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ChangeColorSaturation

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ConvertColorToMac

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ConvertColorToWin

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ConvertColorFromMac

Functioncall:

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

Description:
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.95Ultraschall version 4.00Lua version 5.3 ^ ConvertColorFromWin

Functioncall:

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

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ SetIniFileExternalState

Functioncall:

boolean retval = ultraschall.SetIniFileExternalState(string section, string key, string value, string ini_filename_with_path)

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ GetIniFileExternalState

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountIniFileExternalState_sec

Functioncall:

integer sectioncount = ultraschall.CountIniFileExternalState_sec(string ini_filename_with_path)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountIniFileExternalState_key

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ EnumerateIniFileExternalState_sec

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ EnumerateIniFileExternalState_key

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountSectionsByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountKeysByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CountValuesByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ EnumerateSectionsByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ EnumerateKeysByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ EnumerateValuesByPattern

Functioncall:

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

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetKBIniFilepath

Functioncall:

string kb_ini_path = ultraschall.GetKBIniFilepath()

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ CountKBIniActions

Functioncall:

integer actions = ultraschall.CountKBIniActions(string filename_with_path)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ CountKBIniScripts

Functioncall:

integer scripts = ultraschall.CountKBIniScripts(string filename_with_path)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ CountKBIniKeys

Functioncall:

integer keys = ultraschall.CountKBIniKeys(string filename_with_path)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniActions

Functioncall:

integer consolidate, integer section, string ActionCommandID, string description, string ActionsToBeExecuted = ultraschall.GetKBIniActions(string filename_with_path, integer idx)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniScripts

Functioncall:

integer terminateinstance, integer section, string ActionCommandID, string description, string scriptfile = ultraschall.GetKBIniScripts(string filename_with_path, integer idx)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniKeys

Functioncall:

integer keytype_modifier_midichan, integer key_midinote, string ActionCommandID, integer section = ultraschall.GetKBIniKeys(string filename_with_path, integer idx)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniActionsID_ByActionCommandID

Functioncall:

string retval, integer indexcount, table indices = ultraschall.GetKBIniActionsID_ByActionCommandID(filename_with_path, ActionCommandID)

Description:
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.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniScripts_ByActionCommandID

Functioncall:

string retval, integer indexcount, table indices = ultraschall.GetKBIniScripts_ByActionCommandID(filename_with_path, ActionCommandID)

Description:
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 5.40Ultraschall version 4.2Lua version 5.3 ^ GetKBIniKeys_ByActionCommandID

Functioncall:

string retval, integer indexcount, table indices = ultraschall.GetKBIniKeys_ByActionCommandID(filename_with_path, ActionCommandID)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ SetKBIniActions

Functioncall:

boolean retval, integer actionnumber = ultraschall.SetKBIniActions(string filename_with_path, integer consolidate, integer section, string ActionCommandID, string Description, string ActionCommandIDs, boolean replace)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ SetKBIniScripts

Functioncall:

boolean retval, integer scriptnumber = ultraschall.SetKBIniScripts(string filename_with_path, integer terminate, integer section, string ActionCommandID, string Description, string Scriptname, boolean replace)

Description:
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 5.40Ultraschall version 4.00Lua version 5.3 ^ SetKBIniKeys

Functioncall:

boolean retval, integer keynumber = ultraschall.SetKBIniKeys(string filename_with_path, integer keytype_modifier_midichan, integer key_midinote, string ActionCommandID, integer section, boolean replace)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ DeleteKBIniActions

Functioncall:

boolean retval = ultraschall.DeleteKBIniActions(string filename_with_path, integer idx)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ DeleteKBIniScripts

Functioncall:

boolean retval = ultraschall.DeleteKBIniScripts(string filename_with_path, integer idx)

Description:
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 5.40Ultraschall version 4.00Lua version 5.3 ^ DeleteKBIniKeys

Functioncall:

boolean retval = ultraschall.DeleteKBIniKeys(string filename_with_path, integer idx)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ GetIniFileValue

Functioncall:

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

Description:
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 



^ Reaper version 5.965Ultraschall version 4.00SWS version 2.10.0.1Lua version 5.3 ^ SetIniFileValue

Functioncall:

integer retval = ultraschall.SetIniFileValue(string section, string key, string value, string inifile)

Description:
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 



^ Reaper version 6.02Ultraschall version 4.00SWS version 2.10.0.1Lua version 5.3 ^ QueryKeyboardShortcutByKeyID

Functioncall:

string Shortcutname = ultraschall.QueryKeyboardShortcutByKeyID(integer modifier, integer key)

Description:
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 6.02Ultraschall version 4.2Lua version 5.3 ^ CharacterCodes_ReverseLookup

Functioncall:

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)

Description:
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.02Ultraschall version 4.2Lua version 5.3 ^ CharacterCodes_ReverseLookup_KBIni

Functioncall:

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)

Description:
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.02Ultraschall version 4.2Lua version 5.3 ^ KBIniGetAllShortcuts

Functioncall:

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

Description:
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 6.17Ultraschall version 4.2Lua version 5.3 ^ GetActionCommandIDByFilename

Functioncall:

string ActionCommandID = ultraschall.GetActionCommandIDByFilename(string searchfilename, integer searchsection, optional boolean case_sensitive)

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAcidImport

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigActionMenu

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAdjRecLat

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAdjRecManLat

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAfxCfg

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAllStereoPairs

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAlwaysAllowKB

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigApplyFXTail

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAdjRecManLatIn

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAudioPrShift

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAudioCloseStop

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAudioThreadPr

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAudioCloseTrackWnds

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAutoMute

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAutoMuteFlags

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAutoSaveInt

Functioncall:

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

Description:
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.95Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetSetConfigAutoSaveMode

Functioncall:

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

Description:
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.941Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ GetStartNewFileRecSizeState

Functioncall:

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

Description:
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.941Ultraschall version 4.00SWS version 2.9.7Lua version 5.3 ^ SetStartNewFileRecSizeState

Functioncall:

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

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ GetDeferRunState

Functioncall:

boolean retval = ultraschall.GetDeferRunState(integer deferinstance, optional string scriptidentifier)

Description:
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 5.965Ultraschall version 4.00Lua version 5.3 ^ StopDeferCycle

Functioncall:

boolean retval = ultraschall.StopDeferCycle(string defer_identifier)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ Defer

Functioncall:

boolean retval, optional string defer_identifier = ultraschall.Defer(function func, string deferidentifier, optional integer mode, optional number timer_counter, optional boolean protected)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ SetDeferCycleSettings

Functioncall:

boolean retval = ultraschall.SetDeferCycleSettings(string deferidentifier, optional integer mode, optional number timer_counter)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ GetDeferCycleSettings

Functioncall:

integer mode, integer timer_counter = ultraschall.GetDeferCycleSettings(string deferidentifier)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ IsValidEnvStateChunk

Functioncall:

boolean valid = ultraschall.IsValidEnvStateChunk(string EnvelopeStateChunk)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ MoveTrackEnvelopePointsBy

Functioncall:

integer retval = ultraschall.MoveTrackEnvelopePointsBy(number startposition, number endposition, number moveby, MediaTrack MediaTrack, boolean cut_at_border)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopePoint

Functioncall:

number time, number value, integer shape, number tension, boolean selected, number dBVal, array EnvelopePointObject = ultraschall.GetEnvelopePoint(integer Tracknumber, string EnvelopeName, integer idx)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetClosestEnvelopePointIDX_ByTime

Functioncall:

integer idxpre, array EnvelopePointObjectPre, integer idxpost, array EnvelopePointObjectPost = ultraschall.GetClosestEnvelopePointIDX_ByTime(integer Tracknumber, string EnvelopeName, number CheckTime)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopePointIDX_Between

Functioncall:

string EnvelopeString, array EnvelopePointArray = ultraschall.GetEnvelopePointIDX_Between(integer Tracknumber, string EnvelopeName, number startposition, number endposition)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CheckEnvelopePointObject

Functioncall:

boolean retval = ultraschall.CheckEnvelopePointObject(array EnvelopePointObject)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ IsValidEnvelopePointObject

Functioncall:

boolean retval = ultraschall.IsValidEnvelopePointObject(array EnvelopePointObject)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ SetEnvelopePoints_EnvelopePointObject

Functioncall:

boolean retval = ultraschall.SetEnvelopePoints_EnvelopePointObject(array EnvelopePointObject, boolean sort_in)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ SetEnvelopePoints_EnvelopePointArray

Functioncall:

boolean retval = ultraschall.SetEnvelopePoints_EnvelopePointArray(array EnvelopePointArray, boolean sort_in)

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ DeleteEnvelopePoints_EnvelopePointObject

Functioncall:

boolean retval = ultraschall.DeleteEnvelopePoints_EnvelopePointObject(array EnvelopePointObject)

Description:
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.40Ultraschall version 4.00SWS version 2.8.8Lua version 5.3 ^ DeleteEnvelopePoints_EnvelopePointArray

Functioncall:

boolean retval = ultraschall.DeleteEnvelopePoints_EnvelopePointArray(array EnvelopePointArray)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ AddEnvelopePoints_EnvelopePointObject

Functioncall:

boolean retval = ultraschall.AddEnvelopePoints_EnvelopePointObject(array EnvelopePointObject, boolean sort_in)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ AddEnvelopePoints_EnvelopePointArray

Functioncall:

boolean retval = ultraschall.AddEnvelopePoints_EnvelopePointArray(array EnvelopePointArray, boolean sort_in)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ CreateEnvelopePointObject

Functioncall:

boolean retval, array EnvelopePointObject = ultraschall.CreateEnvelopePointObject(TrackEnvelope TrackEnvelope, integer idx, number time, number value, integer shape, number tension, boolean selected)

Description:
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 5.40Ultraschall version 4.00Lua version 5.3 ^ CountEnvelopePoints

Functioncall:

integer envpoint_count = ultraschall.CountEnvelopePoints(integer Tracknumber, string EnvelopeName)

Description:
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.52Ultraschall version 4.00Lua version 5.3 ^ SetEnvelopeHeight

Functioncall:

boolean retval, string TrackEnvelopeStateChunk = ultraschall.SetEnvelopeHeight(integer Height, boolean Compacted, TrackEnvelope TrackEnvelope, string TrackEnvelopeStateChunk)

Description:
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.52Ultraschall version 4.00Lua version 5.3 ^ GetAllTrackEnvelopes

Functioncall:

array TrackEnvelopeArray, integer number_of_tracks, integer FirstEnvelopeTrackNumber, integer FirstEnvelopeMaster = ultraschall.GetAllTrackEnvelopes()

Description:
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.941Ultraschall version 4.00Lua version 5.3 ^ IsValidEnvelopePointArray

Functioncall:

boolean retval = ultraschall.IsValidEnvelopePointArray(EnvelopePointArray EnvelopePointArray)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetLastEnvelopePoint_TrackEnvelope

Functioncall:

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)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ GetArmState_Envelope

Functioncall:

integer retval = ultraschall.GetArmState_Envelope(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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 5.95Ultraschall version 4.00Lua version 5.3 ^ SetArmState_Envelope

Functioncall:

boolean retval, optional string EnvelopeStateChunk = ultraschall.SetArmState_Envelope(TrackEnvelope TrackEnvelope, integer state, optional string EnvelopeStateChunk)

Description:
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.10Ultraschall version 4.2SWS version 2.10.0.1Lua version 5.3 ^ GetTrackEnvelope_ClickState

Functioncall:

boolean clickstate, number position, MediaTrack track, TrackEnvelope envelope, integer EnvelopePointIDX = ultraschall.GetTrackEnvelope_ClickState(integer mouse_button)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_NumbersOnly

Functioncall:

table values = ultraschall.GetEnvelopeState_NumbersOnly(string state, optional string EnvelopeStateChunk, optional string functionname, optional boolean numbertoggle)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_Act

Functioncall:

integer act, integer automation_settings = ultraschall.GetEnvelopeState_Act(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_Vis

Functioncall:

integer visible, integer lane, integer unknown = ultraschall.GetEnvelopeState_Vis(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_LaneHeight

Functioncall:

integer height, integer compacted = ultraschall.GetEnvelopeState_LaneHeight(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_DefShape

Functioncall:

integer shape, integer pitch_custom_envelope_range_takes, integer pitch_snap_values = ultraschall.GetEnvelopeState_DefShape(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_Voltype

Functioncall:

integer voltype = ultraschall.GetEnvelopeState_Voltype(TrackEnvelope TrackEnvelope, optional string EnvelopeStateChunk)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_PooledEnvInstance

Functioncall:

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)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_PT

Functioncall:

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)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ GetEnvelopeState_EnvName

Functioncall:

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)

Description:
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.05Ultraschall version 4.1Lua version 5.3 ^ GetAllTrackEnvelopes

Functioncall:

integer number_of_trackenvelopes, table TrackEnvelopes_Table = ultraschall.GetAllTrackEnvelopes()

Description:
Returns all TrackEnvelopes of all tracks from the current project as a handy table

The format of the table is as follows:
    TrackEnvelopes[trackenvelope_idx]["Track"] - the idx of the track; 0, for mastertrack, 1, for first track, etc
    TrackEnvelopes[trackenvelope_idx]["EnvelopeObject"] - the TrackEnvelope-object
    TrackEnvelopes[trackenvelope_idx]["EnvelopeName"] - the name of of TrackEnvelopeObject

Returnvalues:
 integer number_of_trackenvelopes the number of TrackEnvelopes found in the current project 
 table TrackEnvelopes_Table all found TrackEnvelopes as a handy table(see description for details) 



^ Reaper version 6.05Ultraschall version 4.1Lua version 5.3 ^ GetAllTakeEnvelopes

Functioncall:

integer number_of_takeenvelopes, table TakeEnvelopes_Table = ultraschall.GetAllTakeEnvelopes()

Description:
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 6.10Ultraschall version 4.1Lua version 5.3 ^ SetEnvelopeState_Vis

Functioncall:

boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_Vis(TrackEnvelope env, integer visibility, integer lane, integer unknown, optional string EnvelopeStateChunk)

Description:
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 6.10Ultraschall version 4.1Lua version 5.3 ^ SetEnvelopeState_Act

Functioncall:

boolean retval = ultraschall.SetEnvelopeState_Act(TrackEnvelope env, integer act, integer automation_settings, optional string EnvelopeStateChunk)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ SetEnvelopeState_DefShape

Functioncall:

boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_DefShape(TrackEnvelope env, integer shape, integer pitch_custom_envelope_range, integer pitch_snap_values, optional string EnvelopeStateChunk)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ SetEnvelopeState_LaneHeight

Functioncall:

boolean retval, string EnvelopeStateChunk = ultraschall.SetEnvelopeState_LaneHeight(TrackEnvelope env, integer height, integer compacted, optional string EnvelopeStateChunk)

Description:
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 5.981Ultraschall version 4.1Lua version 5.3 ^ ActivateEnvelope

Functioncall:

boolean retval = ultraschall.ActivateEnvelope(TrackEnvelope env, optional boolean visible, optional boolean bypass)

Description:
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 6.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackVolumeEnv

Functioncall:

boolean retval = ultraschall.ActivateTrackVolumeEnv(integer track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackVolumeEnv_TrackObject

Functioncall:

boolean retval = ultraschall.ActivateTrackVolumeEnv_TrackObject(MediaTrack track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPanEnv

Functioncall:

boolean retval = ultraschall.ActivateTrackPanEnv(integer track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPanEnv_TrackObject

Functioncall:

boolean retval = ultraschall.ActivateTrackPanEnv_TrackObject(MediaTrack track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPreFXPanEnv

Functioncall:

boolean retval = ultraschall.ActivateTrackPreFXPanEnv(integer track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPreFXPanEnv_TrackObject

Functioncall:

boolean retval = ultraschall.ActivateTrackPreFXPanEnv_TrackObject(MediaTrack track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPreFXVolumeEnv

Functioncall:

boolean retval = ultraschall.ActivateTrackPreFXVolumeEnv(integer track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackPreFXVolumeEnv_TrackObject

Functioncall:

boolean retval = ultraschall.ActivateTrackPreFXVolumeEnv_TrackObject(MediaTrack track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackTrimVolumeEnv

Functioncall:

boolean retval = ultraschall.ActivateTrackTrimVolumeEnv(integer track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ ActivateTrackTrimVolumeEnv_TrackObject

Functioncall:

boolean retval = ultraschall.ActivateTrackTrimVolumeEnv_TrackObject(MediaTrack track)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ GetTakeEnvelopeUnderMouseCursor

Functioncall:

TakeEnvelope env, MediaItem_Take take, number projectposition = ultraschall.GetTakeEnvelopeUnderMouseCursor()

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ IsAnyMuteEnvelopeVisible

Functioncall:

boolean retval = ultraschall.IsAnyMuteEnvelopeVisible(string name)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ IsEnvelope_Track

Functioncall:

boolean retval = ultraschall.IsEnvelope_Track(TrackEnvelope env)

Description:
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.10Ultraschall version 4.1Lua version 5.3 ^ IsTrackEnvelopeVisible_ArrangeView

Functioncall:

boolean retval = ultraschall.IsTrackEnvelopeVisible_ArrangeView(TrackEnvelope env)

Description:
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 5.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_EnumerateStartupEvents

Functioncall:

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)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_EnumerateStartupEvents2

Functioncall:

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)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_AddEvent

Functioncall:

string event_identifier = ultraschall.EventManager_AddEvent(string EventName, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, table Actions)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_IsValidEventIdentifier

Functioncall:

boolean valid, boolean valid_inuse = ultraschall.EventManager_IsValidEventIdentifier(string event_identifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_RemoveEvent

Functioncall:

boolean retval = ultraschall.EventManager_RemoveEvent(string event_identifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_RemoveAllEvents_Script

Functioncall:

boolean retval = ultraschall.EventManager_RemoveAllEvents_Script(string ScriptIdentifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_SetEvent

Functioncall:

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)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_EnumerateEvents

Functioncall:

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)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_EnumerateEvents2

Functioncall:

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)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_CountRegisteredEvents

Functioncall:

integer count_of_registered_events = ultraschall.EventManager_CountRegisteredEvents()

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetLastUpdateTime

Functioncall:

string datetime, number precise_time = ultraschall.EventManager_GetLastUpdateTime()

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_PauseEvent

Functioncall:

boolean retval = ultraschall.EventManager_PauseEvent(string event_identifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_ResumeEvent

Functioncall:

boolean retval = ultraschall.EventManager_ResumeEvent(string event_identifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_Start

Functioncall:

boolean retval = ultraschall.EventManager_Start()

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_Stop

Functioncall:

ultraschall.EventManager_Stop(optional boolean force, optional string ScriptIdentifier)

Description:
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 5.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_AddStartupEvent

Functioncall:

string event_identifier = ultraschall.EventManager_AddStartupEvent(string EventName, integer CheckAllXSeconds, integer CheckForXSeconds, boolean StartActionsOnceDuringTrue, boolean EventPaused, function CheckFunction, table Actions)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_RemoveStartupEvent2

Functioncall:

boolean retval = ultraschall.EventManager_RemoveStartupEvent2(integer id)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_RemoveStartupEvent

Functioncall:

boolean retval = ultraschall.EventManager_RemoveStartupEvent(string event_identifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_CountStartupEvents

Functioncall:

integer count_startup_events = ultraschall.EventManager_CountStartupEvents()

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_SetStartupEvent

Functioncall:

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)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetPausedState2

Functioncall:

boolean paused_state = ultraschall.EventManager_GetPausedState2(string EventIdentifier)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetPausedState

Functioncall:

boolean paused_state = ultraschall.EventManager_GetPausedState(integer id)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetEventIdentifier

Functioncall:

string event_identifier = ultraschall.EventManager_GetEventIdentifier(integer id)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetLastCheckfunctionState

Functioncall:

boolean check_state, number last_statechange_precise_time = ultraschall.EventManager_GetLastCheckfunctionState(integer id)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetRegisteredEventID

Functioncall:

integer id = ultraschall.EventManager_GetRegisteredEventID(string EventIdentifier)

Description:
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.965Ultraschall version 4.00Lua version 5.3 ^ EventManager_GetLastCheckfunctionState2

Functioncall:

boolean check_state, number last_statechange_precise_time = ultraschall.EventManager_GetLastCheckfunctionState2(string EventIdentifier)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_DebugMode

Functioncall:

ultraschall.EventManager_DebugMode(boolean toggle)

Description:
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.982Ultraschall version 4.00Lua version 5.3 ^ EventManager_DebugMode_UserSpace

Functioncall:

integer userspace_count, table userspace = ultraschall.EventManager_DebugMode_UserSpace(integer index)

Description:
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.40Ultraschall version 4.00Lua version 5.3 ^ ReadFullFile

Functioncall:

string contents, integer length_of_file, integer number_of_lines = ultraschall.ReadFullFile(string filename_with_path, boolean binary)

Description:
Return contents of filename_with_path.

Returns nil in case of an error.

Returnvalues:
 string contents the contents of the whole file. 
 integer length_of_file the number of bytes of the file 
 integer number_of_lines number of lines in file (-1 if parameter binary is set to true) 

Parameters:
 string filename_with_path filename of the file to be read 
 boolean binary true if the file shall be read as a binary file; false if read as ASCII. Default is ASCII. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadValueFromFile

Functioncall:

string contents, string linenumbers, integer numberoflines, integer number_of_foundlines = ultraschall.ReadValueFromFile(string filename_with_path, string value)

Description:
Return contents of filename_with_path.

If "value" is given, it will return all lines, containing the value in the file "filename_with_path".
The second line-numbers return-value is very valuable when giving a "value". "Value" is not case-sensitive.
The value 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

Returnvalues:
 string contents the contents of the file, or the lines that contain parameter value in it, separated by a newline 
 string linenumbers a string, that contains the linenumbers returned as a , separated csv-string 
 integer numberoflines_in_file the total number of lines in the file 
 integer number_of_foundlines the number of found lines 

Parameters:
 string filename_with_path filename of the file to be read 
 string value the value to look in the file for. Not case-sensitive. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadLinerangeFromFile

Functioncall:

string contents, boolean correctnumberoflines, integer number_of_lines = ultraschall.ReadLinerangeFromFile(string filename_with_path, integer firstlinenumber, integer lastlinenumber)

Description:
Return contents of filename_with_path, from firstlinenumber to lastlinenumber. Counting of linenumbers starts with 1 for the first line.
The returned string contains all requested lines, separated by a newline.

Returns nil, if the linenumbers are invalid.

Returnvalues:
 string contents the contents the lines of the file, that you requested 
 boolean correctnumberoflines true, if the number of lines are returned, as requested; false if fewer lines are returned 
 integer number_of_lines the number of read lines 

Parameters:
 string filename_with_path filename of the file to be read 
 integer firstlinenumber the first linenumber to be returned. First line in the file begins with 1! 
 integer lastlinenumber the last linenumber to be returned; -1, for the whole file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ MakeCopyOfFile

Functioncall:

boolean retval = ultraschall.MakeCopyOfFile(string input_filename_with_path, string output_filename_with_path)

Description:
Copies input_filename_with_path to output_filename_with_path.
Only textfiles! For binary-files use MakeCopyOfFile_Binary() instead!

Returns true, if it worked, false if it didn't.

Returnvalues:
 boolean retval true, if copy worked, false if it didn't. 

Parameters:
 string input_filename_with_path filename of the file to copy 
 string output_filename_with_path filename of the copied file to be created. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ MakeCopyOfFile_Binary

Functioncall:

boolean retval = ultraschall.MakeCopyOfFile_Binary(string input_filename_with_path, string output_filename_with_path)

Description:
Copies input_filename_with_path to output_filename_with_path as binary-file.

returns false in case of an error

Returnvalues:
 boolean retval returns true, if copy worked; false if it didn't 

Parameters:
 string input_filename_with_path filename of the file to copy 
 string output_filename_with_path filename of the copied file, that shall be created 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadBinaryFileUntilPattern

Functioncall:

integer length, string content = ultraschall.ReadBinaryFileUntilPattern(string input_filename_with_path, string pattern)

Description:
Returns a binary file, up until a pattern. The pattern is not case-sensitive.

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 length the length of the returned data 
 string content the content of the file, that has been read until pattern 

Parameters:
 string filename_with_path filename of the file to be read 
 string pattern a pattern to search for. Case-sensitive. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadBinaryFileFromPattern

Functioncall:

integer length, string content = ultraschall.ReadBinaryFileFromPattern(string input_filename_with_path, string pattern)

Description:
Returns a binary file, from pattern onwards. The pattern is not case-sensitive.

The 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 length the length of the returned data 
 string content the content of the file, that has been read from pattern to the end 

Parameters:
 string filename_with_path filename of the file to be read 
 string pattern a pattern to search for. Case-sensitive. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ CountLinesInFile

Functioncall:

integer linesinfile = ultraschall.CountLinesInFile(string filename_with_path)

Description:
Counts lines in a textfile. In binary files, the number of lines may be weird and unexpected!
Returns -1, if no such file exists.

Returnvalues:
 integer linesinfile number of lines in a textfile; -1 in case of error 

Parameters:
 string filename_with_path filename of the file to be read 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadFileAsLines_Array

Functioncall:

array contents, boolean correctnumberoflines, integer number_of_lines = ultraschall.ReadFileAsLines_Array(string filename_with_path, integer firstlinenumber, integer lastlinenumber)

Description:
Return contents of filename_with_path, from firstlinenumber to lastlinenumber as an array. Counting of linenumbers starts with 1 for the first line.
The returned array contains all requested lines, which each entry holding one returned line.

Returns nil, if the linenumbers are invalid.

Returnvalues:
 array contents the contents the lines of the file, that you requested as an array, in which each entry hold one line of the file 
 boolean correctnumberoflines true, if the number of lines are returned, as you requested; false if fewer lines are returned 
 integer number_of_lines the number of lines returned 

Parameters:
 string filename_with_path filename of the file to be read 
 integer firstlinenumber the first linenumber to be returned. First line in the file begins with 1! 
 integer lastlinenumber the last linenumber to be returned; -1, read all lines in the file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ ReadBinaryFile_Offset

Functioncall:

integer length, string content = ultraschall.ReadBinaryFile_Offset(string input_filename_with_path, integer startoffset, integer numberofbytes)

Description:
Returns the contents of a binary file from startoffset until startoffset+numberofbytes.

When setting startoffset to a negative value, it will read from the end of the file, means:
-100 will start -100 characters before the end of the file and numberofbytes will read from that point on    

Returns -1, if file can not be opened.

Returnvalues:
 integer length the length of the returned part of the file, might be shorter than requested, if file ends before 
 string content the content of the file, that has been read 

Parameters:
 string input_filename_with_path filename of the file to be read 
 integer startoffset the offset, at where to begin the fileread. 0 for the beginning of the file; negative values set offset from the end of the file 
 integer numberofbytes the number of bytes to read. -1 for until the end of the file. If there are fewer bytes than requested, the returned string will be shorter. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ GetLengthOfFile

Functioncall:

integer length_of_file = ultraschall.GetLengthOfFile(string filename_with_path)

Description:
Returns the length of the file filename_with_path in bytes.
Will return -1, if no such file exists.

Returnvalues:
 integer length_of_file the length of the file in bytes. -1 in case of error 

Parameters:
 string filename_with_path filename to write the value to 


^ Reaper version 5.77Ultraschall version 4.00Lua version 5.3 ^ CountDirectoriesAndFilesInPath

Functioncall:

integer filecount, integer dircount = ultraschall.CountDirectoriesAndFilesInPath(string path)

Description:
returns the number of files and directories in path

returns -1, in case of error

Returnvalues:
 integer filecount the number of files found in path 
 integer dircount the number of directories found in path 

Parameters:
 string path the path to count the files and directories from 


^ Reaper version 5.77Ultraschall version 4.00Lua version 5.3 ^ GetAllFilenamesInPath

Functioncall:

integer filecount, array files = ultraschall.GetAllFilenamesInPath(string path)

Description:
returns the number of files and the filenames in path

returns -1, in case of error

Returnvalues:
 integer filecount the number of files found in path 
 array files the filenames found in path 

Parameters:
 string path the path to get the filenames from 


^ Reaper version 5.77Ultraschall version 4.00Lua version 5.3 ^ GetAllDirectoriesInPath

Functioncall:

integer filecount, array directories = ultraschall.GetAllDirectoriesInPath(string path)

Description:
returns the number of directories and the directorynames in path

returns -1, in case of error

Returnvalues:
 integer filecount the number of directories found in path 
 array files the directories found in path 

Parameters:
 string path the path to get the directories from 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ CheckForValidFileFormats

Functioncall:

string fileformat, boolean supported_by_reaper, string mediatype = ultraschall.CheckForValidFileFormats(string filename_with_path)

Description:
Returns the fileformat of a Reaper-supported-file, images, audios(opus and m4a missing, though!), and video(mp4-video missing, though!).
Note: Checks the file itself and does not check for correct file-extension. Reaper needs the correct file-extension or it can't read an otherwise valid imagefile.
      For example: if you want to import a GIF, renamed to filename.JPG, Reaper will not be able to read it. Only when the extension is the same as the file itself(filename.GIF).

Returns nil in case of an error

Returnvalues:
 string fileformat the format of the file; JPG, PNG, GIF, LCF, ICO, WAV, AIFF, ASF/WMA/WMV, MP3, MP3 -ID3TAG, FLAC, MKV/MKA/MKS/MK3D/WEBM, AVI, RPP_PROJECT, unknown 
 boolean supported_by_reaper true, if importing of the fileformat is supported by Reaper; false, if not 
 string mediatype the type of the media; Image, Audio, Audio/Video, Video, Reaper 

Parameters:
 string filename_with_path the file to check for it's image-fileformat 


^ Reaper version 5.77Ultraschall version 4.00Lua version 5.3 ^ DirectoryExists

Functioncall:

boolean retval = ultraschall.DirectoryExists(string path, string directory)

Description:
Checks, if a directory exists in path.

On Linux: path and directory are case-sensitive!

Returns false in case of error.

Returnvalues:
 boolean retval true, directory exists; false, directory does not exist 

Parameters:
 string path the path, in which to look for the existence of parameter directory 
 string directory the name of the directory to check for in path 


^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ OnlyFilesOfCertainType

Functioncall:

integer foundfilecount, array foundfilearray = ultraschall.OnlyFilesOfCertainType(array filearray, string filetype)

Description:
Returns the filenames_with_path from a filearray, that are of a certain filetype

returns -1 in case of an error

Returnvalues:
 integer foundfilecount the number of files that contain the right filetype 
 array foundfilearray an array with all the files that contain the right filetype 

Parameters:
 array filearray an array with files to check for; index is 1-based 
 string fileformat the format of the file; JPG, PNG, GIF, LCF, ICO, WAV, AIFF, ASF/WMA/WMV, MP3, MP3 -ID3TAG, FLAC, MKV/MKA/MKS/MK3D/WEBM, AVI, RPP_PROJECT, unknown 


^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ GetReaperWorkDir

Functioncall:

string current_workdir = ultraschall.GetReaperWorkDir()

Description:
returns the current workdir, which is the directory. If you create a file without giving a path, this file will be created in this work-dir.

Returnvalues:
 string current_workdir the current workdir of Reaper 



^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ DirectoryExists2

Functioncall:

boolean retval = ultraschall.DirectoryExists2(string Path)

Description:
returns, if Path is an existing path.

returns false in case of an error

Returnvalues:
 boolean retval true, if path exists; false, if not 

Parameters:
 string Path the path to check for 


^ Reaper version 5.95Ultraschall version 4.00Lua version 5.3 ^ SetReaperWorkDir

Functioncall:

boolean retval = ultraschall.SetReaperWorkDir(string Path)

Description:
sets a new current working directory for Reaper. This requires a restart of Reaper to take effect, due API-limitations!
                        
returns false in case of an error

Returnvalues:
 boolean retval true, if path could be set; false, if not 

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


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ GetPath

Functioncall:

string path, string filename = ultraschall.GetPath(string str, optional string sep)

Description:
returns the path of a filename-string

returns "", "" in case of error

Returnvalues:
 string path the path as a string 
 string filename the filename, without the path 

Parameters:
 string str the path with filename you want to process 
 string sep a separator, with which the function knows, how to separate filename from path; nil to use the last useful separator in the string, which is either / or \\ 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ CreateValidTempFile

Functioncall:

string tempfilename = ultraschall.CreateValidTempFile(string filename_with_path, boolean create, string suffix, boolean retainextension)

Description:
Tries to determine a valid temporary filename. Will check filename_with_path with an included number between 0 and 16384 to create such a filename.
You can also add your own suffix to the filename.

The pattern is: filename_with_path$Suffix~$number.ext (when retainextension is set to true!)

If you wish, you can also create this temporary-file as an empty file.

The path of the tempfile is always the same as the original file.

Returns nil in case of failure.

Returnvalues:
 string tempfilename the valid temporary filename found 

Parameters:
 string filename_with_path the original filename 
 boolean create true, if you want to create that temporary file as an empty file; false, just return the filename 
 string suffix if you want to alter the temporary filename with an additional suffix, use this parameter 
 boolean retainextension true, keep the extension(if existing) at the end of the tempfile; false, just add the suffix~number at the end. 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ WriteValueToFile

Functioncall:

integer retval = ultraschall.WriteValueToFile(string filename_with_path, string value, optional boolean binarymode, optional boolean append)

Description:
Writes value to filename_with_path. Will replace any previous content of the file if append is set to false. Returns -1 in case of failure, 1 in case of success.

returns -1 in case of an error

Returnvalues:
 integer retval -1 in case of failure, 1 in case of success 

Parameters:
 string filename_with_path the filename with it's path 
 string value the value to export, can be a long string that includes newlines and stuff. nil is not allowed! 
 boolean binarymode true or nil, it will store the value as binary-file; false, will store it as textstring 
 boolean append true, add the value to the end of the file; false or nil, write value to file and erase all previous data in the file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ WriteValueToFile_Insert

Functioncall:

integer retval = ultraschall.WriteValueToFile_Insert(string filename_with_path, integer linenumber, string value)

Description:
Inserts value into a file at linenumber. All lines, up to linenumber-1 come before value, all lines at linenumber to the end of the file will come after value.
Will return -1, if no such line exists.

Note: non-binary-files only!

Returnvalues:
 integer retval 1, in case of success, -1 in case of error 

Parameters:
 string filename_with_path filename to write the value to 
 integer linenumber the linenumber, at where to insert the value into the file 
 string value the value to be inserted into the file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ WriteValueToFile_Replace

Functioncall:

integer retval = ultraschall.WriteValueToFile_Replace(string filename_with_path, integer startlinenumber, integer endlinenumber, string value)

Description:
Replaces the linenumbers startlinenumber to endlinenumber in a file with value. All lines, up to startlinenumber-1 come before value, all lines at endlinenumber+1 to the end of the file will come after value.
Will return -1, if no such lines exists.

Note: non-binary-files only!

Returnvalues:
 integer retval 1, in case of success, -1 in case of error 

Parameters:
 string filename_with_path filename to write the value to 
 integer startlinenumber the first linenumber, to be replaced with value in the file 
 integer endlinenumber the last linenumber, to be replaced with value in the file 
 string value the value to be inserted into the file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ WriteValueToFile_InsertBinary

Functioncall:

integer retval = ultraschall.WriteValueToFile_InsertBinary(string filename_with_path, integer byteposition, string value)

Description:
Inserts value into a file at byteposition. All bytes, up to byteposition-1 come before value, all bytes at byteposition to the end of the file will come after value.
Will return -1, if no such line exists.

Note: good for binary files

Returnvalues:
 integer retval 1, in case of success, -1 in case of error 

Parameters:
 string filename_with_path filename to write the value to 
 integer byteposition the byteposition, at where to insert the value into the file 
 string value the value to be inserted into the file 


^ Reaper version 5.40Ultraschall version 4.00Lua version 5.3 ^ WriteValueToFile_ReplaceBinary

Functioncall:

integer retval = ultraschall.WriteValueToFile_ReplaceBinary(string filename_with_path, integer startbyteposition, integer endbyteposition, string value)

Description:
Replaces content in the file from startbyteposition to endbyteposition-1 with value. All bytes, up to startbyteposition-1 come before value, all bytes from (and including)endbyteposition to the end of the file will come after value.
Will return -1, if no such line exists.

Note: good for binary files

Returnvalues:
 integer retval 1, in case of success, -1 in case of error 

Parameters:
 string filename_with_path filename to write the value to 
 integer startbyteposition the first byte in the file to be replaced, starting with 1, if you want to replace at the beginning of the file. Everything before startposition will be kept. 
 integer endbyteposition the first byte after the replacement. Everything from endbyteposition to the end of the file will be kept. 
 string value the value to be inserted into the file 


^ Reaper version 5.965Ultraschall version 4.00Lua version 5.3 ^ GetAllRecursiveFilesAndSubdirectories

Functioncall:

integer found_dirs, array dirs_array, integer found_files, array files_array = ultraschall.GetAllRecursiveFilesAndSubdirectories(string path)

Description:
Returns all subdirectories and files within a given path.

Might take some time with many folders/files.


Returns -1 in case of an error.

Returnvalues:
 integer found_dirs the number of directories found; -1, in case of an error 
 array dirs_array the full path to the found directories as an array 
 integer found_files the number of files found 
 array files_array the full path to the found files as an array 

Parameters:
 string path the path from where to retrieve the files and subdirectories 


^ Reaper version 5.99Ultraschall version 4.00Lua version 5.3 ^ SaveSubtitles_SRT

Functioncall:

integer retval = ultraschall.SaveSubtitles_SRT(string subtitle_filename_with_path, table subtitle_table)

Description:
saves the subtitles from the subtitle-table.

The subtitles-table is expected to be of the following format:

    subtitle_table[subtitle_index]["start"]   = starttime in seconds
    subtitle_table[subtitle_index]["end"]     = endtime in seconds
    subtitle_table[subtitle_index]["caption"] = the caption, which shall be shown from start to end-time

returns -1 in case of an error

Returnvalues:
 string guid the guid of the marker/region of the marker with a specific index 

Parameters:
 string subtitle_filename_with_path the filename of the subtitle-file, into which you want to store the subtitles 
 table Table the subtitle-table, which holds all captions and the start- and endtimes of displaying the caption 


^ Reaper version 5.965Ultraschall version 4.00Lua version 5.3 ^ ReadSubtitles_SRT

Functioncall:

integer Captions_Counter, table Captions = ultraschall.ReadSubtitles_SRT(string filename_with_path)

Description:
parses an srt-subtitle-file and returns its contents as table

returns nil in case of an error

Returnvalues:
 integer Captions_Counter the number of captions in the file 
 table Captions the Captions as a table of the format:
    Captions[index]["start"]= the starttime of this caption in seconds
    Captions[index]["end"]= the endtime of this caption in seconds
    Captions[index]["caption"]= the caption itself 

Parameters:
 string filename_with_path the filename with path of the subrip srt-file 


^ Reaper version 6.02Ultraschall version 4.00Lua version 5.3 ^ MoveFileOrFolder

Functioncall:

boolean retval = ultraschall.MoveFileOrFolder(string file_foldername, string oldpath, string newpath)

Description:
Moves a file or folder from oldpath to newpath.

returns false in case of an error

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

Parameters:
 string file_foldername the folder- or filename, which you want to move 
 string oldpath the old path, in which the file or folder is located 
 string newpath the new path, into which the file or folder shall be moved 


^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_StartCopying

Functioncall:

integer instance_number = ultraschall.CopyFile_StartCopying()

Description:
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.




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_IsCurrentlyCopying

Functioncall:

boolean retval = ultraschall.CopyFile_IsCurrentlyCopying()

Description:
Returns, if the any copying-instance is (still) currently copying files.




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetCurrentlyRunningCopyInstances

Functioncall:

integer number_of_instances = ultraschall.CopyFile_GetCurrentlyRunningCopyInstances()

Description:
Returns the number of copying-instances currently started by CopyFile_StartCopying




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetCurrentlyCopiedFile

Functioncall:

integer number_of_remaining_files, string filename, integer remaining_bytes_to_copy, integer percentage = ultraschall.CopyFile_GetCurrentlyCopiedFile()

Description:
Returns the information about the file currently copied




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_SetBufferSize

Functioncall:

boolean retval = ultraschall.CopyFile_SetBufferSize(integer buffersize)

Description:
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.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetBufferSize

Functioncall:

integer buffer_size = ultraschall.CopyFile_GetBufferSize()

Description:
Returns the current buffer-size in bytes.




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_AddFileToQueue

Functioncall:

integer current_copyqueue_position = ultraschall.CopyFile_AddFileToQueue(string filename, string targetfilename, boolean overwrite)

Description:
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.


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.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetCopiedStatus

Functioncall:

string filename, boolean already_processed, string error_message, string error_code = ultraschall.CopyFile_GetCopiedStatus(integer fileindex)

Description:
Returns the copystatus of a file in the copy-queue

Will return -1 in case of an error.


Parameters:
 integer fileindex the index of the file within the copying-queue 


^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_FlushCopiedFiles

Functioncall:

ultraschall.CopyFile_FlushCopiedFiles()

Description:
Flushes the queue for the already copied files.

This invalidates the files-index given by CopyFile_AddFileToQueue!




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_StopCopying

Functioncall:

ultraschall.CopyFile_StopCopying()

Description:
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.




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_Pause

Functioncall:

boolean retval = ultraschall.CopyFile_Pause(boolean toggle)

Description:
Pauses the copying of the files in the copying-queue.

Will return false in case of an error.


Parameters:
 integer toogle true, pause the copying; false, go on with copying of the files 


^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetPausedState

Functioncall:

boolean retval = ultraschall.CopyFile_GetPausedState()

Description:
Returns the current paused-state of the background-copying




^ Reaper version 5.40Ultraschall version 4.1Lua version 5.3 ^ CopyFile_GetRemainingFilesToCopy

Functioncall:

integer filecount = ultraschall.CopyFile_GetRemainingFilesToCopy()

Description:
Returns the number of files that still need to be copied.




^ Reaper version 6.12Ultraschall version 4.2Lua version 5.3 ^ BatchConvertFiles

Functioncall:

boolean retval = ultraschall.BatchConvertFiles(table inputfilelist, table outputfilelist, table RenderTable, optional boolean BWFStart, optional integer PadStart, optional integer PadEnd, optional string FXStateChunk)

Description:
Converts files using Reaper's own BatchConverter.

This function will open another instance of Reaper that runs the batchconverter, so it will still open the batch-converter-list for the time of conversion.
Though as it is another instance, you can safely go back to the old instance of Reaper.

This function will probably NOT finish before the batch-converter is finished with conversion, keep this in mind.

Will take away the focus from the currently focused window, as Reaper puts keyboard-focus to the newly started Reaper-instance that does the batch-conversion.    

returns nil in case of an error

Returnvalues:
 table inputfilelist a table of filenames+path, that shall be converted 
 table outputfilelist a table of the target filenames+path, where the first filename is the target for the first inputfilename, etc 
 table RenderTable the settings for the conversion; just use the render-table-functions to create one 
 optional boolean BWFStart true, include BWF-start; false or nil, don't include BWF-start 
 optional integer PadStart the start of the padding in seconds; nil, to omit it 
 optional integer PadEnd the end of the padding in seconds; nil, to omit it 
 optional string FXStateChunk an FXChain as FXStateChunk; with that you can add fx on top of the to-convert-files. 

Parameters:
 boolean retval true, conversion was successfully started; false, conversion didn't start 


^ Reaper version 5.975Ultraschall version 4.2Lua version 5.3 ^ IsValidFXStateChunk

Functioncall:

boolean retval = ultraschall.IsValidFXStateChunk(string StateChunk)

Description:
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.10Ultraschall version 4.2Lua version 5.3 ^ GetFXFromFXStateChunk

Functioncall:

string fx_lines, integer startoffset, integer endoffset = ultraschall.GetFXFromFXStateChunk(string FXStateChunk, integer fxindex)

Description:
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 5.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLearn_FXStateChunk

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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 5.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLearn_MediaItem

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_MediaItem(MediaItem MediaItem, integer fxid, integer id)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLearn_MediaTrack

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLearn_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetParmAlias_FXStateChunk

Functioncall:

integer parm_idx, string parm_aliasname = ultraschall.GetParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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.975Ultraschall version 4.1Lua version 5.3 ^ GetParmAlias_MediaTrack

Functioncall:

integer parm_idx, string parm_aliasname = ultraschall.GetParmAlias_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetParmModulationChunk_FXStateChunk

Functioncall:

string parm_modulation_chunk = ultraschall.GetParmModulationChunk_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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 5.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLFOLearn_FXStateChunk

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLFOLearn_MediaItem

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_MediaItem(MediaItem MediaItem, integer fxid, integer id)

Description:
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.975Ultraschall version 4.00Lua version 5.3 ^ GetParmLFOLearn_MediaTrack

Functioncall:

integer parm_idx, string parmname, integer midi_note, integer checkboxflags, optional string osc_message = ultraschall.GetParmLFOLearn_MediaTrack(MediaTrack MediaTrack, integer fxid, integer id)

Description:
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.977Ultraschall version 4.00SWS version 2.10.0.1Julian Sader's plugin version 0.986Lua version 5.3 ^ ScanDXPlugins

Functioncall:

ultraschall.ScanDXPlugins(optional boolean re_scan)

Description:
(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.979Ultraschall version 4.00Lua version 5.3 ^ DeleteParmLearn_FXStateChunk

Functioncall:

boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ DeleteParmAlias_FXStateChunk

Functioncall:

boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ DeleteParmLFOLearn_FXStateChunk

Functioncall:

boolean retval, string alteredFXStateChunk = ultraschall.DeleteParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ SetParmLFOLearn_FXStateChunk

Functioncall:

boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id, integer midi_note, integer checkboxflags, optional string osc_message)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ SetParmLearn_FXStateChunk

Functioncall:

boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmLearn_FXStateChunk(string FXStateChunk, integer fxid, integer id, integer midi_note, integer checkboxflags, optional string osc_message)

Description:
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 5.979Ultraschall version 4.1Lua version 5.3 ^ SetParmAlias_FXStateChunk

Functioncall:

boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer id, string parmalias)

Description:
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.979Ultraschall version 4.1Lua version 5.3 ^ SetParmAlias2_FXStateChunk

Functioncall:

boolean retval, optional string alteredFXStateChunk = ultraschall.SetParmAlias2_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx, string parmalias)

Description:
Sets an already existing Parm-Learn-entry of an FX-plugin from an FXStateChunk.

Unlike SetParmAlias_FXStateChunk, the parameter parmidx 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 parmidx 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.979Ultraschall version 4.00Lua version 5.3 ^ SetFXStateChunk

Functioncall:

boolean retval, optional string alteredStateChunk = ultraschall.SetFXStateChunk(string StateChunk, string FXStateChunk, optional integer TakeFXChain_id)

Description:
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 5.975Ultraschall version 4.00Lua version 5.3 ^ GetFXStateChunk

Functioncall:

string FXStateChunk, integer linenumber = ultraschall.GetFXStateChunk(string StateChunk, optional integer TakeFXChain_id)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ AddParmLFOLearn_FXStateChunk

Functioncall:

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)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ AddParmLearn_FXStateChunk

Functioncall:

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)

Description:
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 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, 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 5.979Ultraschall version 4.1Lua version 5.3 ^ AddParmAlias_FXStateChunk

Functioncall:

boolean retval, optional string alteredFXStateChunk = ultraschall.AddParmAlias_FXStateChunk(string FXStateChunk, integer fxid, integer parmidx, string parmalias)

Description:
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.979Ultraschall version 4.00Lua version 5.3 ^ CountParmAlias_FXStateChunk

Functioncall:

integer count = ultraschall.CountParmAlias_FXStateChunk(string FXStateChunk, integer fxid)

Description:
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.979Ultraschall version 4.1Lua version 5.3 ^ CountParmLearn_FXStateChunk

Functioncall:

integer count = ultraschall.CountParmLearn_FXStateChunk(string FXStateChunk, integer fxid)

Description:
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 5.979Ultraschall version 4.00Lua version 5.3 ^ CountParmLFOLearn_FXStateChunk

Functioncall:

integer count = ultraschall.CountParmLFOLearn_FXStateChunk(string FXStateChunk, integer fxid)

Description:
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.977Ultraschall version 4.00SWS version 2.10.0.1Julian Sader's plugin version 0.986Lua version 5.3 ^ ScanVSTPlugins

Functioncall:

ultraschall.ScanVSTPlugins(optional boolean clear_cache)

Description:
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 5.977Ultraschall version 4.00SWS version 2.10.0.1Julian Sader's plugin version 0.986Lua version 5.3 ^ AutoDetectVSTPluginsFolder

Functioncall:

ultraschall.AutoDetectVSTPluginsFolder()

Description:
Auto-detects the vst-plugins-folder.




^ Reaper version 6.02Ultraschall version 4.00Lua version 5.3 ^ CountFXStateChunksInStateChunk

Functioncall:

integer count_of_takefx_statechunks, integer count_of_trackfx_statechunks = ultraschall.CountFXStateChunksInStateChunk(string StateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ RemoveFXStateChunkFromTrackStateChunk

Functioncall:

string altered_TrackStateChunk = ultraschall.RemoveFXStateChunkFromTrackStateChunk(string TrackStateChunk)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ RemoveFXStateChunkFromItemStateChunk

Functioncall:

string alteredItemStateChunk = ultraschall.RemoveFXStateChunkFromItemStateChunk(string ItemStateChunk, integer take_id)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ LoadFXStateChunkFromRFXChainFile

Functioncall:

string FXStateChunk = ultraschall.LoadFXStateChunkFromRFXChainFile(string filename, integer trackfx_or_takefx)

Description:
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.02Ultraschall version 4.00Lua version 5.3 ^ SaveFXStateChunkAsRFXChainfile

Functioncall:

integer retval = ultraschall.SaveFXStateChunkAsRFXChainfile(string filename, string FXStateChunk)

Description:
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 6.02Ultraschall version 4.00Lua version 5.3 ^ GetAllRFXChainfilenames

Functioncall:

integer count_of_RFXChainfiles, array RFXChainfiles = ultraschall.GetAllRFXChainfilenames()

Description:
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 6.02Ultraschall version 4.00SWS version 2.10.0.1Lua version 5.3 ^ GetRecentFX

Functioncall:

integer count_of_RecentFX, array RecentFX = ultraschall.GetRecentFX()

Description:
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.11Ultraschall version 4.1Lua version 5.3 ^ GetTrackFX_AlternativeName

Functioncall:

string alternative_fx_name = ultraschall.GetTrackFX_AlternativeName(integer tracknumber, integer fx_id)

Description:
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.11Ultraschall version 4.1Lua version 5.3 ^ GetTakeFX_AlternativeName

Functioncall:

string alternative_fx_name = ultraschall.GetTakeFX_AlternativeName(integer tracknumber, integer take_id, integer fx_id)

Description:
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.11Ultraschall version 4.1Lua version 5.3 ^ SetTrackFX_AlternativeName

Functioncall:

boolean retval = ultraschall.SetTrackFX_AlternativeName(integer tracknumber, integer fx_id, string newname)

Description:
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.11Ultraschall version 4.1Lua version 5.3 ^ SetTakeFX_AlternativeName

Functioncall:

boolean retval = ultraschall.SetTakeFX_AlternativeName(integer tracknumber, integer take_id, integer fx_id, string newname)

Description:
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.02Ultraschall version 4.2Lua version 5.3 ^ GetFXSettingsString_FXLines

Functioncall:

string fx_statestring_base64, string fx_statestring = ultraschall.GetFXSettingsString_FXLines(string fx_lines)

Description:
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.02Ultraschall version 4.1Lua version 5.3 ^ GetParmModTable_FXStateChunk

Functioncall:

table ParmModulationTable = ultraschall.GetParmModTable_FXStateChunk(string FXStateChunk, integer fxindex, integer parmodindex)

Description:
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["PARMLINK"]               - the Link from MIDI or FX parameter-checkbox
                                                      true, checked; false, unchecked
            ParmModTable["PARMLINK_LINKEDPLUGIN"]  - the selected plugin; nil, if not available
                                                        -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_LINKEDPARMIDX"] - the id of the linked parameter; -1, if none is linked yet; nil, if not available;
                                                   - will be ignored, when PARMLINK_LINKEDPLUGIN_RELATIVE is set
                                                        When MIDI, this is irrelevant.
                                                        When FX-parameter:
                                                          0 to n; 0 for the first; 1, for the second, 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, uses only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX)
            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 6.10Ultraschall version 4.1Lua version 5.3 ^ CreateDefaultParmModTable

Functioncall:

table ParmModTable = ultraschall.CreateDefaultParmModTable()

Description:
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"]=1              - 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"]=true
                                                        - Enable parameter modulation, baseline value(envelope overrides)-checkbox;
                                                          true, checked; false, unchecked
                ParmModTable["PARAMOD_BASELINE"]=0     - Enable parameter modulation, baseline value(envelope overrides)-slider;
                                                            0.000 to 1.000

                ParmModTable["AUDIOCONTROL"]=false           - 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"]=1          - the Track audio channel-dropdownlist; When stereo, the first stereo-channel;
                                                                nil, if not available
                ParmModTable["AUDIOCONTROL_STEREO"]=0        - 0, just use mono-channels; 1, use the channel AUDIOCONTROL_CHAN plus
                                                                  AUDIOCONTROL_CHAN+1; nil, if not available
                ParmModTable["AUDIOCONTROL_ATTACK"]=300      - the Attack-slider of Audio Control Signal; 0-1000 ms; nil, if not available
                ParmModTable["AUDIOCONTROL_RELEASE"]=300     - the Release-slider; 0-1000ms; nil, if not available
                ParmModTable["AUDIOCONTROL_MINVOLUME"]=-24   - the Min volume-slider; -60dB to 11.9dB; must be smaller than AUDIOCONTROL_MAXVOLUME;
                                                                  nil, if not available
                ParmModTable["AUDIOCONTROL_MAXVOLUME"]=0     - the Max volume-slider; -59.9dB to 12dB; must be bigger than AUDIOCONTROL_MINVOLUME;
                                                                  nil, if not available
                ParmModTable["AUDIOCONTROL_STRENGTH"]=1      - the Strength-slider; 0(0%) to 1000(100%)
                ParmModTable["AUDIOCONTROL_DIRECTION"]=1     - 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"]=false                    - if the LFO-checkbox checked; true, checked; false, unchecked
                                                                 Note: if true, this needs all LFO_-entries to be set
                ParmModTable["LFO_SHAPE"]=0                  - 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"]=0              - 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"]=false         - the Tempo sync-checkbox; true, checked; false, unchecked
                ParmModTable["LFO_SPEED"]=0.124573          - the LFO Speed-slider; 0(0.0039Hz) to 1(8.0000Hz); nil, if not available
                ParmModTable["LFO_STRENGTH"]=1              - the LFO Strength-slider; 0.000(0.0%) to 1.000(100.0%)
                ParmModTable["LFO_PHASE"]=0                 - the LFO Phase-slider; 0.000 to 1.000; nil, if not available
                ParmModTable["LFO_DIRECTION"]=1             - the LFO Direction-radiobuttons; -1, Negative; 0, Centered; 1, Positive
                ParmModTable["LFO_PHASERESET"]=0            - the LFO Phase reset-dropdownlist;
                                                                0, On seek/loop(deterministic output)
                                                                1, Free-running(non-deterministic output)
                                                                nil, if not available

                ParmModTable["PARMLINK"]=false              - the Link from MIDI or FX parameter-checkbox
                                                                true, checked; false, unchecked
                ParmModTable["PARMLINK_LINKEDPLUGIN"]=-1    - 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"]=nil - 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, uses only the plugin linked absolute(the one linked with PARMLINK_LINKEDPARMIDX)                                                                      
                
                ParmModTable["PARMLINK_LINKEDPARMIDX"]=-1   - 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"]=0           - the Offset-slider; -1.00(-100%) to 1.00(+100%); nil, if not available
                ParmModTable["PARMLINK_SCALE"]=1            - the Scale-slider; -1.00(-100%) to 1.00(+100%); nil, if not available


                ParmModTable["MIDIPLINK"]=false             - 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"]=nil           - the MIDI-bus selected in the button-menu;
                                                                0 to 15 for bus 1 to 16;
                                                                nil, if not available
                ParmModTable["MIDIPLINK_CHANNEL"]=nil       - 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"]=nil  - 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"]=nil      - 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         - 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"]=true      - if the position of the ParmMod-window is altered and currently open;
                                                                 nil, unchanged; 0, unopened; 1, open
                ParmModTable["WINDOW_XPOS"]=0                - the x-position of the altered ParmMod-window in pixels; nil, default position
                ParmModTable["WINDOW_YPOS"]=40               - the y-position of the altered ParmMod-window in pixels; nil, default position
                ParmModTable["WINDOW_RIGHT"]=594             - the right-position of the altered ParmMod-window in pixels;
                                                                 nil, default position; only readable
                ParmModTable["WINDOW_BOTTOM"]=729            - 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.10Ultraschall version 4.1Lua version 5.3 ^ IsValidParmModTable

Functioncall:

boolean retval = ultraschall.IsValidParmModTable(table ParmModTable)

Description:
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.02Ultraschall version 4.1Lua version 5.3 ^ AddParmMod_ParmModTable

Functioncall:

string FXStateChunk = ultraschall.AddParmMod_ParmModTable(string FXStateChunk, integer fxindex, table ParmModTable)

Description:
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)
               &n