Ultraschall-API 4.9 - 1663 Lua-Functions -"Razor Edit"

[Meo-Ada Mespotine]

After over 6 years of coding, I'm proud to announce the release of the

Ultraschall-API 4.9 - a 1662 Lua-functions-library for Reaper

which can be found at https://ultraschall.fm/api or installed via ReaPack, using https://github.com/Ultraschall/ultra..._api_index.xml

This API is intended to make programming Reaper much more easier, trying to give you access to many hard-to-code corners of Reaper, improving programming workflows, that are inconvenient to work with using Reaper's own API, making debugging of scripts much easier and much more.
This API was to be used within Ultraschall only, but quickly evolved into a huge 1000+ function-library, that many 3rd-party programmers and scripters may find use in, with many useful features, like:

• ReaPack-installable, add it to your ReaPack-installation and you can install it easily
• Rendering - you can render your projects without having to use the render-dialog. You can customize the rendering-workflow in every way you want. Just create a renderstring and pass it over to RenderProject_RenderCFG or RenderProjectRegions_RenderCFG
• Navigation, Follow and Arrangeview-Manipulation - get/set cursors, zoom, autoscroll-management, scroll, etc
• ArrangeView-Snapshots - you can save, retrieve snapshots of the arrangeview, including position, zoomstates to quickly jump through parts of your project
• Trackstates - you can access and set all(!) track-states available
• ProjectStates - you can access all and set many project-states available
• EventManager - run actions, when certain events occur. Which events? You decide!
• Mediaitem-states - you can access and set many mediaitem-states (more will follow)
• File access - many helperfunctions for reading, writing, copying files. No more hassle writing it yourself! e.g ReadFullFile, WriteValueToFile, etc
• Cough-Mute-management - you can write your own cough-buttons, that set the state of the mute-envelope of a track easily
• Marker - extensive set of marker functions, get, set, export, import, enumerate, etc
• Spectrogram - you can program the spectrogram-view
• Routing - you can set Sends/Receives and HWOuts more straightforward than with Reaper's own Routing-functions. Includes mastertrack as well.
• Get MediaItems - you can get all media-items within a time-range AND within the tracks you prefer; a 2D-approach e.g. GetAllMediaItemsBetween and GetMediaItemsAtPosition, etc
• Gaps between items - you can get the gaps between items in a track, using GetGapsBetweenItems
• Edit item(s) - Split, Cut, Copy, Paste, Move, RippleCut, RippleInsert, SectionCut by tracks AND time/start to endposition e.g. RippleCut, RippleInsert, SectionCut, SplitMediaItems_Position, MoveMediaItemsBefore_By, MoveMediaItemsSectionTo and many more
• Previewing MediaItems and files - you can preview MediaItems and files without having to start playback of a project
• KB-Ini-Management - manipulate the reaper-kb.ini-file with custom-settings
• Checking for Datatypes - check all datatypes introduced with Ultraschall-API and all Lua/Reaper-datatypes
• UndoManagement - functions for easily making undoing of functions as well as preventing creating an undo-point
• RunCommand for Items/Tracks - apply actions to specific items/tracks
• Checking for changed projecttabs - check, if projecttabs have been added/removed
• ExtState-Management - an extensive set of functions for working with extstates as well as ini-files
• Data Manipulation - manipulate a lot of your data, including bitwise-integers, tables, etc
• Clipboard-Management - get items from clipboard, put them to clipboard, even multiple ones
• Error Messaging System - all functions create useful error-messages that can be shown using, eg: ShowLastErrorMessage, for easier debugging
• Custom-Defer-functions, who allow you to control, how often a deferred function shall be executed (every n'th cycle/second)
• Child-Scripts, who allow starting scripts AND passing parameters/returnvalues/values between two scripts. Even multiple-instances of one script can be started, where communication with each scriptinstance is possible on an individual basis.
  Means: Start Childscript.lua twice, and you can communicate with ChildScript.lua(instance1) and ChildScript.lua(instance2) individually, which is difficult to do otherwise.
• Custom-Markers and Regions, allow you to create different markertypes of the scheme _custommarker1: text of the marker
  You can add, set, count, enum, delete them like normal markers. All you need to set the custommarker-name (custommarker1 in the above example) and this will be used for the custom-markers/custom-regions of your choice
• Razor Edit functions - you can manipulate, nudge, get/set Razor-Edit-Areas very easily
• Localization of your scripts - via a translationfile. Now you can let people do translations for you without having to add them into your script by hand.
• FXStateChunk-Management - access all the nice gems the API itself doesn't, though StateChunks provide
• Parameter Modulation - code your parameter modulation. No more UI needed
• tons of other helper-functions
• my Reaper-Internals Documentation AND

it's fully documented.

Find the introduction to it here: https://mespotin.uber.space/Ultrasch..._Concepts.html

[Meo-Ada Mespotine]

For a description of concepts I introduce with it, see Functions Reference Page
Downloads and the latest hotfixes can be found at the Downloads Page.

Installation via ReaPack can be done using the index-URL: https://github.com/Ultraschall/ultra..._api_index.xml

Happy coding and let's see, what you can do with it

Meo Mespotine

For more information about Ultraschall itself, see ultraschall.fm and if you want to support us, see my support-page or the Ultraschall-donationpage for donating to us.

PS: This is public-beta, so it probably contains many bugs I couldn't find yet. Please report them, if you happen to find one. Read more about this in the Bugreporting and Feature Requests chapter of the docs.


Jesus..I need a break after this...


See the Ultraschall-Feature-of-the-Week-posts for some of the nice functionalities I provide.
Click here to go to the first post.

[Meo-Ada Mespotine]

Placeholder 2

[Meo-Ada Mespotine]

Placeholder 3

[Meo-Ada Mespotine]

Placeholder 4

[Meo-Ada Mespotine]

Placeholder 5 for something big to come...

[LowlyOP]

i'm scared.

[Meo-Ada Mespotine]

6 days, until you can easily

Color Items and Tracks:

-- Meo Mespotine - 30. November 2018
-- Cycles colors of MediaItems and MediaTracks. It's using a ColorTable with SonicRainboomColorStyle

dofile(reaper.GetResourcePath().."/UserPlugins/ultraschall_api.lua")

ColorTable=ultraschall.CreateSonicRainboomColorTable()           -- create ColorTable SonicRainboom-style
NumMediaItems,MediaItemArray=ultraschall.GetAllMediaItems() -- get all MediaItems in the current project as MediaItemArray

function main()
  -- Let's cycle the colors
  counter=counter-1 
  CycledColorTable=ultraschall.CycleTable(ColorTable,math.floor(counter))  -- cycle the colors in the ColorTable
  retval = ultraschall.ApplyColorTableToTrackColors(CycledColorTable, 1) -- apply the cycled ColorTable to MediaTrack-colors
  ultraschall.ApplyColorTableToItemColors(CycledColorTable, 1, MediaItemArray) -- apply the cycled ColorTable to MediaItem-colors
  reaper.defer(main)
end

counter=0 -- a simple counter for the offset of the cycling
main() -- Let's start to boogie

or even influence brightness, contrast and saturation:

-- Ultraschall-API demoscript by Meo Mespotine 29.10.2018
-- 
-- change brightness, contrast and saturation of the trackcolors of all tracks.
-- will apply, by default, the Ultraschall-colorscheme "Sonic Rainboom"

dofile(reaper.GetResourcePath().."/UserPlugins/ultraschall_api.lua")

-- Colorize Tracks
ColorTable = ultraschall.CreateSonicRainboomColorTable()
ultraschall.ApplyColorTableToTrackColors(ColorTable, 2)

gfx.init("Change Track-Color's Brightness, Contrast and Saturation",300,200,0,500,400)
gfx.setfont(1,"times",16)

brightness=0
contrast=0
saturation=0

function changecolor(value, changetype)
  -- change the color, according to selected type
  for i=1, reaper.CountTracks(0) do 
    R,G,B=ultraschall.ConvertColorReverse(reaper.GetTrackColor(reaper.GetTrack(0,i-1)))
    if changetype==1 then red, green, blue = ultraschall.ChangeColorBrightness(R,G,B, value) end -- brightness
    if changetype==2 then red, green, blue = ultraschall.ChangeColorContrast(R,G,B, value, 255+value) end -- contrast
    if changetype==3 then red, green, blue = ultraschall.ChangeColorSaturation(R,G,B, value) end -- saturation
    newcol=ultraschall.ConvertColor(red,green,blue)
    reaper.SetTrackColor(reaper.GetTrack(0,i-1), newcol)
  end
end

function main()
  -- get pressed key  
  A=gfx.getchar()  
  
  -- brightness
  if A==49 then changecolor(-3, 1) brightness=brightness-3 end 
  if A==50 then changecolor(3, 1) brightness=brightness+3 end 
  -- contrast
  if A==51 then changecolor(-3, 2) contrast=contrast-3 end 
  if A==52 then changecolor(3, 2) contrast=contrast+3 end 
  -- saturation
  if A==53 then changecolor(-3, 3) saturation=saturation-3 end 
  if A==54 then changecolor(3, 3) saturation=saturation+3 end
  
  if A~=-1 then 
    gfx.x=0 gfx.y=0
    gfx.drawstr("Change\n Brightness(keys 1 and 2): "..brightness.."\n Contrast(keys 3 and 4)  : "..contrast.."\n Saturation(keys 5 and 6): "..saturation)
    gfx.update()
    reaper.defer(main) 
  end
end

A=1
main()

[Meo-Ada Mespotine]

4.8 - "Sparks - When do I get to sing my way" - 8th of April 2023

Has now 1652 functions, with 37 new ones

new in this release:

• Docs-Find-functions
  Added now a lot of functions to access the docs of a function directly via API.
  You can also use the various Find-functions to search for functions matching certain words and slugs.
  With that, you can build your own API-search-tools.
  Oh: and you can search the Config-Vars too!
  
• UTF8/string-functions for Lua
  Various helperfunctions for dealing with strings and utf8-encoded strings. They'll be added to the string-module of Lua.
  
• Store RenderTable as extstate
  You can store and retrieve RenderTables from/to extstates and projextstates. So you can store multiple render-settings in a project.
  So if you have different render-settings for different parts of your project, you can store and restore them now from extstates without having to spam the render-presets.

New features in 4.8

• Debug: Debug_ShowCurrentContext - calling this function returns/shows the current sourcefile, linenumber and function-context(for debug)
• HelperFunctions: ConvertIniStringToTable - converts a loaded ini-file into a table
• HelperFunctions: string.has_alphanumeric - returns if a string has a alphanumeric-character
• HelperFunctions: string.has_control - returns if a string has a control-character
• HelperFunctions: string.has_digits - returns if a string has a digit-character
• HelperFunctions: string.has_hex - returns if a string has a hex-character
• HelperFunctions: string.has_letter - returns if a string has a letter-character
• HelperFunctions: string.has_lowercase - returns if a string has a lowercase-character
• HelperFunctions: string.has_printable - returns if a string has a printable-character
• HelperFunctions: string.has_space - returns if a string has a space-character
• HelperFunctions: string.has_uppercase - returns if a string has a uppercase-character
• HelperFunctions: string.utf8_len - returns the length of an utf8-encoded string; works like string.len
• HelperFunctions: string.utf8_sub - gets the substring of an utf8-encoded string; works like string.sub
• Docs: Docs_FindReaperApiFunction_Pattern - searches for api-functions(including extensions) that follow a search pattern
• Docs: Docs_FindReaperConfigVar_Pattern - searches for configuration variables that follow a search pattern
• Docs: Docs_FindUltraschallApiFunction_Pattern - searches for Ultraschall Api-functions that follow a search pattern
• Docs: Docs_GetAllReaperApiFunctionnames - returns all reaper-API-functionnames existing in the docs(includes extensions)
• Docs: Docs_GetAllUltraschallApiFunctionnames - returns all Ultraschall-API-functionnames existing in the docs(includes extensions)
• Docs: Docs_GetReaperApiFunction_Call - returns the functioncall of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Description - returns the description of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Params - returns the parameters of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Retvals - returns the returnvalues of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Requires - returns the required dependencies of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Tags - returns the tags of a Reaper-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Call - returns the functioncall of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Description - returns the description of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Params - returns the parameters of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Retvals - returns the returnvalues of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Requires - returns the required dependencies of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Tags - returns the tags of a Ultraschall-API-function(includes extensions)
• Docs: Docs_LoadReaperApiDocBlocs - (re)loads the entries of the Reaper api-documentation
• Docs: Docs_LoadReaperConfigVarsDocBlocs - (re)loads the entries of the config-var-documentation
• Docs: Docs_LoadUltraschallApiDocBlocs - (re)loads the entries of the Ultraschall api-documentation
• Rendering: GetRenderTable_ExtState - gets a RenderTable stored in an extstate
• Rendering: GetRenderTable_ProjExtState - gets a RenderTable stored in a projextstate
• Rendering: SetRenderTable_ExtState - stores a RenderTable in an extstate
• Rendering: SetRenderTable_ProjExtState - stores a RenderTable in a projextstate
  
  Changes from 4.75 to 4.8
• Docs: Reaper Internals - updated docs to Reaper 6.78, SWS 2.13.2.0, ReaFab 0.3.10, FeaLlm 0.4.1 and added PeloReaper 2023.02.19
• FXManagement: SetFXStateChunk - didn't work properly on tracks without an existing FXChain -> fixed now(thanks to tompad)

Please update it via ReaPack using: https://github.com/Ultraschall/ultra..._api_index.xml

[tompad]

Originally Posted by Meo-Ada Mespotine

4.8 - "Sparks - When do I get to sing my way" - 8th of April 2023

Has now 1652 functions, with 37 new ones

new in this release:

• Docs-Find-functions
  Added now a lot of functions to access the docs of a function directly via API.
  You can also use the various Find-functions to search for functions matching certain words and slugs.
  With that, you can build your own API-search-tools.
  Oh: and you can search the Config-Vars too!
  
• UTF8/string-functions for Lua
  Various helperfunctions for dealing with strings and utf8-encoded strings. They'll be added to the string-module of Lua.
  
• Store RenderTable as extstate
  You can store and retrieve RenderTables from/to extstates and projextstates. So you can store multiple render-settings in a project.
  So if you have different render-settings for different parts of your project, you can store and restore them now from extstates without having to spam the render-presets.

New features in 4.8

• Debug: Debug_ShowCurrentContext - calling this function returns/shows the current sourcefile, linenumber and function-context(for debug)
• HelperFunctions: ConvertIniStringToTable - converts a loaded ini-file into a table
• HelperFunctions: string.has_alphanumeric - returns if a string has a alphanumeric-character
• HelperFunctions: string.has_control - returns if a string has a control-character
• HelperFunctions: string.has_digits - returns if a string has a digit-character
• HelperFunctions: string.has_hex - returns if a string has a hex-character
• HelperFunctions: string.has_letter - returns if a string has a letter-character
• HelperFunctions: string.has_lowercase - returns if a string has a lowercase-character
• HelperFunctions: string.has_printable - returns if a string has a printable-character
• HelperFunctions: string.has_space - returns if a string has a space-character
• HelperFunctions: string.has_uppercase - returns if a string has a uppercase-character
• HelperFunctions: string.utf8_len - returns the length of an utf8-encoded string; works like string.len
• HelperFunctions: string.utf8_sub - gets the substring of an utf8-encoded string; works like string.sub
• Docs: Docs_FindReaperApiFunction_Pattern - searches for api-functions(including extensions) that follow a search pattern
• Docs: Docs_FindReaperConfigVar_Pattern - searches for configuration variables that follow a search pattern
• Docs: Docs_FindUltraschallApiFunction_Pattern - searches for Ultraschall Api-functions that follow a search pattern
• Docs: Docs_GetAllReaperApiFunctionnames - returns all reaper-API-functionnames existing in the docs(includes extensions)
• Docs: Docs_GetAllUltraschallApiFunctionnames - returns all Ultraschall-API-functionnames existing in the docs(includes extensions)
• Docs: Docs_GetReaperApiFunction_Call - returns the functioncall of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Description - returns the description of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Params - returns the parameters of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Retvals - returns the returnvalues of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Requires - returns the required dependencies of a Reaper-API-function(includes extensions)
• Docs: Docs_GetReaperApiFunction_Tags - returns the tags of a Reaper-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Call - returns the functioncall of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Description - returns the description of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Params - returns the parameters of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Retvals - returns the returnvalues of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Requires - returns the required dependencies of a Ultraschall-API-function(includes extensions)
• Docs: Docs_GetUltraschallApiFunction_Tags - returns the tags of a Ultraschall-API-function(includes extensions)
• Docs: Docs_LoadReaperApiDocBlocs - (re)loads the entries of the Reaper api-documentation
• Docs: Docs_LoadReaperConfigVarsDocBlocs - (re)loads the entries of the config-var-documentation
• Docs: Docs_LoadUltraschallApiDocBlocs - (re)loads the entries of the Ultraschall api-documentation
• Rendering: GetRenderTable_ExtState - gets a RenderTable stored in an extstate
• Rendering: GetRenderTable_ProjExtState - gets a RenderTable stored in a projextstate
• Rendering: SetRenderTable_ExtState - stores a RenderTable in an extstate
• Rendering: SetRenderTable_ProjExtState - stores a RenderTable in a projextstate
  
  Changes from 4.75 to 4.8
• Docs: Reaper Internals - updated docs to Reaper 6.78, SWS 2.13.2.0, ReaFab 0.3.10, FeaLlm 0.4.1 and added PeloReaper 2023.02.19
• FXManagement: SetFXStateChunk - didn't work properly on tracks without an existing FXChain -> fixed now(thanks to tompad)

Please update it via ReaPack using: https://github.com/Ultraschall/ultra..._api_index.xml

Splendid! ;-)
Thanks a lot!

[JackOrez]

Is there some place I can get the latest version? The Releases page at github hasn't had an updated version in almost a year. I don't and probably will never use ReaPack, nothing against its devs, it's just that my daw system is never connected to the net., which makes it about a billion times easier to troubleshoot if something goes wrong.

My only connection to the net is a mobile device.

Thank you

[Meo-Ada Mespotine]

Do you mean Ultraschall(for podcasting) or Ultraschall API(for programming Reaper)?

[JackOrez]

API for REAPER