|
|
|
06-07-2018, 02:28 PM
|
#1
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Reaper Internals - DevDocs & Tutorials about the secret internal life of Reaper
While learning Reaper to develop stuff for Ultraschall.fm, I started to document things for the others in our project, as well as a resource for myself.
The whole thing is far away from being a proper developer-doc, but you may or may not see use in these docs, so I uploaded them.
Some are work in progress and some are far from finished, while others are more updated versions of the docs available in Cocko's Wiki.
All these docs are creative commons cc-by-nc-sa, so feel free to use them, share them and have fun with it.
See also: Tutorials, created by the community
API-Docs:
Reaper Api Docs(improved)
This is my own version of the API-docs of Reaper, where I try to add all the information that's missing, like parameter/retval-descriptions, function-descriptions, etc.
I also added the C++-functions and I structured the index to reflect the individual use-case-areas appearing in the API.
This is work in progress, but maybe it's useful for you already.
https://forum.cockos.com/showpost.ph...2&postcount=21
I wrote a small introduction there on how to use Reaper's defer-function.
More detailinfo: https://forum.cockos.com/showpost.ph...99&postcount=7
Thoughts on require vs dofile in Lua
Tutorial for HiDPI/Retina in gfx-scripts
Web RC-Api
How to program WebRemoteControl?
Video API
a web-version of Reaper's video-processor-docs
Fileformats and Datastructures
Fileformat Descriptions
descriptions for various config-files of Reaper
LiceCap.ini-doc
Describes the config-file of Cocko's LiceCap-Screenrecording-tool.
Full Actionlist as of Reaper 5.941
The full actionlist as of Reaper 5.941. Includes Menu-only-actions as well(those aren't shown in the actionlist).
Reserved commandids for scripts
This lists all commandids, that are reserved for ReaScripts, separated into the individual sections.
Funfact: About 11997-scripts can be added to each section
Config Variables
The config-variables as used by SNM_GetIntConfigVar(), SNM_SetIntConfigVar(), SNM_GetDoubleConfigVar() and SNM_SetDoubleConfigVar(), as well as the C++-only function get_config_var().
You can set many options, checkboxes and configuration-values with them.
These are fairly complete with only a handful missing(I couldn't trigger them, maybe you can help me with them).
All Config-Variables, that are triggered by actions.
This lists all toggle-actions, who trigger config-variables.
They are documented with values in int/double/string and bitfield.
To know, how to read them, I suggest you to read the Config Variables-docs above.
Render-CFG-Codes
In Projectfiles as well as in the configfile for render-presets, the render-settings are stored using a string.
In this document, I tried to reverse-engineer and document, how these strings work, how they are built and how to make them work.
Includes all formats, except m4a, as this is Mac-only and I don't have a Mac to document them..
With this, you can build your own render-functions/scripts! I already successfully did that
See the render-codes-ini-file below, that feature all code-segments for fps and resolution of video, mp3, flac, opus and ogg.
StateChunk-docs
Envelope StateChunk
This documents envelope-statechunks quite complete. I also included docs for automation-items.
The automation-item-docs feature both, the docs about how to include one automation-item into your own envelope, as well as the automation-item themselves.
Note: the automation-items themselves are only available in RPP-projectfiles and .ReaperAutoItem-files.
MediaItem StateChunk
My attempt at documenting MediaItem-Statechunks, as the docs in Cocko's Wiki is heavily outdated.
Still work in progress, especially all the MIDI stuff is wrong/incomplete and there are entries I haven't found out yet, what they do.
In parts, it's already helpful, anyway
the state-chunk-entries of Parameter Learning/Modulation/Aliases
misc
https://github.com/Ultraschall/ultra...s-ChildIDs.txt - child-hwndids for Reaper-windows(incomplete)
the difference between dofile and require
when you want to build your own Lua-function-library
Helpful-Ini-Files
Reaper Actions as ini
An ini-file that features all actions with their description from Reaper5.941
cmdid=description
gfx.getkey()-codes
This ini-file features all codes that are returned by gfx.getkey() and their ASCII-representation.
That way, you can display, which key is typed. Good to find out easily, which gfx.getkey-code you need now in your script.
reaper-kb.ini - KEY-codes
This ini-file includes all(!) codes and their representation of all keyboard/midi-shortcuts available in Reaper.
Good for analysing, which codes are used in your kb.ini, if you want to display shortcuts in another way, rather than the actions-window-only.
See Fileformat Descriptions above for a full description of reaper-kb.ini
reaper-kb.ini - factory default KEY-codes
The reaper-kb.ini does not include shortcuts, that are factory-default-settings, only custom shortcuts. So I documented the factory-default-ones out and made a handy ini out of it.
See Fileformat Descriptions above for a full description of reaper-kb.ini and in how to work with factory-default-shortcuts
Render codes
The rendercfg-codes as an ini-file, for many formats like DDP, AIF, MP3, FLAC, Video, OPUS and OGG.
The sections are the file-formats (like [OGG] or [FLAC]).
You can find in all sections a key called Renderstring, in which the renderstring-template is stored.
All changeable parts are replaced by [FormatAlterID].
e.g. for OPUS:
Code:
Renderstring=U2dnTwAA[KBPS][MODE][Complexity]AAAA==
Replace the [KBPS] [MODE] [Complexity] with the values of the corresponding keys in the section OPUS.
e.g.:
KBPS_xxx - where xxx is the bitrate-number
MODE_xxx - where xxx is the mode
Complexity_xxx - where xxx is the complexity-number.
So a renderstring with OPUS, Mode:VBR, Bitrate: 24kbps, Complexity:5 would result in this string:
Code:
U2dnTwAAwEEABQAAAA==
MODE_VBR=A
KBPS_24=wEE
Complexity_5=BQ
The Render-codes for the Audio-CD-rendering. Works like the render-string-codes above, but is limited to AudioCD. Supports LeadInSilence up to 100 seconds.
Tools
Display altered config-variables
If you want to use config-variables but don't know, which one is behind the checkbox of your choice, use this. It will display changes to ReaConsole.
Also prepared for string-variables, which are only available in pre-releases of Reaper, yet.
Display altered configfile-entries
This displays changes in classic-ini-files, eg. reaper.ini. Every time an entry is altered, it will be displayed into the ReaConsole.
Supports only standard ini-files
[section]
key=value
For monitoring-tools of StateChunks(Project, Item, Envelope, Tracks), head over to the following post: https://forum.cockos.com/showpost.ph...0&postcount=65
A LangPack, which displays to the left of the section-location of the text.
https://raw.githubusercontent.com/Ul...ReaperLangPack
HWND-displayer - to get the position and attributes of hwnds
Maybe some of the stuff is helpful for you. If you want to motivate me to add more stuff/complete stuff, you can head over to http://ultraschall.fm/danke/, where you can donate stuff to our team
Cheers
Meo-Ada Mespotine
Last edited by Meo-Ada Mespotine; 01-04-2022 at 08:18 PM.
|
|
|
06-07-2018, 04:06 PM
|
#2
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
What an impressive collection and intense reverse engineering work !
Ill have to take a look :P
Thanks for sharing all that
Not that other doc compilation can be found of ReaTeam Doc repository. It contains formatted doc like Web Interface, REAPER as CLI paramters etc.. I added this infos here just as a complement.
EDIT: very nice how you decode the render config settings !!
Last edited by X-Raym; 06-07-2018 at 04:14 PM.
|
|
|
06-07-2018, 04:29 PM
|
#3
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Quote:
Originally Posted by X-Raym
Not that other doc compilation can be found of ReaTeam Doc repository. It contains formatted doc like Web Interface, REAPER as CLI paramters etc.. I added this infos here just as a complement.
|
https://github.com/ReaTeam/Doc
|
|
|
06-08-2018, 01:13 AM
|
#4
|
Human being with feelings
Join Date: Jun 2011
Location: Belgium
Posts: 5,246
|
Wow!
Great work. Thanks for sharing, Mesopotine.
__________________
In a time of deceit telling the truth is a revolutionary act.
George Orwell
|
|
|
06-09-2018, 05:06 AM
|
#5
|
Human being with feelings
Join Date: Oct 2017
Location: Black Forest
Posts: 5,067
|
Indeed, thanks a lot man! Will trying to digest all that info
|
|
|
06-12-2018, 09:11 AM
|
#6
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Thanks
Will add more info, like TrackStateChunks and a first draft of how a rpp-projectfile works, but hadn't time to write that stuff down properly, yet.
|
|
|
06-12-2018, 10:31 AM
|
#7
|
Human being with feelings
Join Date: Sep 2008
Location: Calgary, AB, Canada
Posts: 6,551
|
Have you considered hosting everything on Github and formatting it with Markdown or one of the other styles that Github can display? It would make files like your Project State Chunk much easier to read, and they're still easy as hell to edit (automatically or by hand).
|
|
|
06-12-2018, 11:03 AM
|
#8
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
Quote:
Have you considered hosting everything on Github
|
+1 !
You could then use GitHub pages right on master branch.
|
|
|
06-13-2018, 09:52 AM
|
#9
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Yes, I'm working on my own documentation-system, that makes the whole thing much easier to maintain and manage, with a easy to maintain docformat(the API-Docs is already converted into a prototype-version of it).
It will also allow you more ways to convert it into the docformat of your choice, whether it is a wiki, pdf, latex, markdown, whatever.
When that stuff is working, I will put it on GitHub for everyone to add information.
But it's still in development and I wanted to share the information right now, even if it's still far away from good format.
But yeah, I'm working on it. Will focus on that from autumn on.
Up until then, you can find work in progress-stuff in this Git-Repository: https://github.com/Ultraschall/ultra...nd-reaper-docs
|
|
|
06-14-2018, 03:22 PM
|
#10
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
@mespotine
Hi !
Is there any way to get Project Sample Rate and Project Setings Media Recording Bit Rate of wave files ?
The two keys/entries inspector scripts don't show me any results for these fields.
EDIT: Forgot about project rate, I remember I add a trick to do that, just need to get the sample pos of 1second with time map function :P
EDIT: don't worry I think I will just put a pop up and let the user choose. Simplest to implement than reverse engineering all the different possible format.
Last edited by X-Raym; 06-14-2018 at 03:30 PM.
|
|
|
06-15-2018, 06:53 AM
|
#11
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
@X-Raym
The easiest way would be probably, search in my config-vars-doc for the text of the inputbox/dropdownlist/checkbox, whose setting you want to know.
I typed the description-texts as exact as possible, so you can find it probably quite easy.
If it isn't there, it is either not accessible or a project-config-variable only, which is probably only available using the C++-only-functions
projectconfig_var_addr and projectconfig_var_getoffs but I have not idea how to work with them.
Probably a exposure-FR for SWS...
|
|
|
06-15-2018, 08:49 AM
|
#12
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
It indeed seems to be controlled by this variable as the name suggest.
We need SWS to expose API function for that in ReaScript
|
|
|
06-19-2018, 09:37 AM
|
#13
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I filed a FR, but it is already done by SWS's GetIntConfigVar and GetDoubleConfigVar-functions already, so I closed it again.
|
|
|
07-03-2018, 11:30 AM
|
#14
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I updated the ReaScript-API-Doc. It now features the programming-language-selection, as you are used in the original one supplied with Reaper.
I also added descriptions for the new 5.9x+-functions...
Means: it is the freshest ReaScript-ApiDoc online currently, until X-Raym updates his
@X-Raym
I use my own docfile for the automatic generation of this API-doc, as I'm not happy with parsing the ReaScript-html. Would it help you for your API-docs? Especially the search-functionality from your docs and the more details from my one(parameters, retvals, "categorial"-tags) would be a great combination...
I'll upload my docfile soon, as soon as it's finished structurally(a few weeks probably)...
Last edited by Meo-Ada Mespotine; 07-03-2018 at 11:39 AM.
|
|
|
07-03-2018, 12:27 PM
|
#15
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
@mespotine
I recently build my own generator (it parsed the reascript-help.html and make it HTML 5 semantic with interactivity like the search list and the click/copy) so now new versions will be instantly generated, and so my ReaScript API doc could be updated at every REAPER / SWS updates in very little time :P
|
|
|
07-03-2018, 12:32 PM
|
#16
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
But indeed your version have nice features too, at some point it may be interested to find a way to add these metadatas (REAPER version etc) inside my version. Maybe by parsing the reaper and sws changelog if new API functions are written in a consistent way.
Function category is nice too but it is less required with changelog. I even stripped the function list from the page, and only kept the one in the sidebar.
|
|
|
07-04-2018, 01:57 AM
|
#17
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
@mespotine
Did you find a way to get/set the Render Output file Name ? It is called RENDER_PATTERN in the .rpp.
|
|
|
07-04-2018, 02:42 PM
|
#18
|
Human being with feelings
Join Date: Oct 2017
Location: Black Forest
Posts: 5,067
|
Good question, would love to know that as well!
|
|
|
07-05-2018, 07:54 AM
|
#19
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Getting and setting it in the rpp into the currently opened project?
The latter, as far as I know, is not available currently, not even with the new get_config_var_string()-function.
But if you need that for writing rendering-scripts....well...just a few more weeks of patience and you'll get what you want, probably (hint hint nudge nudge) ^^
In regards of the docs, I also add proper retval and parameter-descriptions, as they are very much needed. This could be important for your version too.
The changelog isn't a good enough source, as some changes aren't documented or only in the pre-changelogs, that don't necessarily reflect the finished release.
I remember, there was a new function added into the API recently, that wasn't in the changelogs, but don't remember it right now...
|
|
|
07-05-2018, 08:33 AM
|
#20
|
Human being with feelings
Join Date: Oct 2017
Location: Black Forest
Posts: 5,067
|
Well, in my case it would be: getting the render file + path and use the data in a Reascript.
|
|
|
07-05-2018, 08:55 AM
|
#21
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
It's only possible, when you save the project and read it from the rpp-file itself.
It would be possible, if we could access the ProjectStateChunk(I once filed a FeatureRequest for that), but currently, it isn't possible in any other way, except reading it from the rpp.
|
|
|
07-05-2018, 09:15 AM
|
#22
|
Human being with feelings
Join Date: Oct 2017
Location: Black Forest
Posts: 5,067
|
I see. Well, not awfully terrible, but would be great if we had the possibilty in the future. Let's hope the Devs include it
|
|
|
07-05-2018, 09:25 AM
|
#23
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
Well, bump my FR for ProjectStateChunks. The more different people bump it up, the higher the chance for the devs to include it
It would allow tons of new Use-Cases and programs....
|
|
|
07-05-2018, 09:27 AM
|
#24
|
Human being with feelings
Join Date: Oct 2017
Location: Black Forest
Posts: 5,067
|
I just did a search, couldn't find it. Point me there, an I'll sign it :P
|
|
|
07-05-2018, 09:40 AM
|
#25
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
|
|
|
07-18-2018, 08:08 AM
|
#26
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I updated the render-code-docs. They include now, how to way to go to generate all render-codes; new additions WavPack, OGG, GIF, LCF AudioCD.. M4A is still missing, as this is Mac-only and I don't have a Mac to document that:
Render-CFG-Codes
I also made a more complete ini-file of render-codes, that can be put together with the information included.
Video render codes
The rendercfg-codes as an ini-file, for many formats like DDP, AIF, MP3, FLAC, Video, OPUS and OGG.
The sections are the file-formats (like [OGG] or [FLAC]).
You can find in all sections a key called Renderstring, in which the renderstring-template is stored.
All changeable parts are replaced by [FormatAlterID].
e.g. for OPUS:
Code:
Renderstring=U2dnTwAA[KBPS][MODE][Complexity]AAAA==
Replace the [KBPS] [MODE] [Complexity] with the values of the corresponding keys in the section OPUS.
e.g.:
KBPS_xxx - where xxx is the bitrate-number
MODE_xxx - where xxx is the mode
Complexity_xxx - where xxx is the complexity-number.
So a renderstring with OPUS, Mode:VBR, Bitrate: 24kbps, Complexity:5 would result in this string:
Code:
U2dnTwAAwEEABQAAAA==
MODE_VBR=A
KBPS_24=wEE
Complexity_5=BQ
|
|
|
07-21-2018, 04:25 PM
|
#27
|
Human being with feelings
Join Date: Nov 2008
Location: London, UK
Posts: 2,583
|
Wow, amazing work and contribution Meo!
|
|
|
07-22-2018, 04:44 AM
|
#28
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I debugged some of the descriptions, specifically for WAVPACK, WAV, MP3(CBR), MP3(ABR) and Video.
Should be more accurate now.
https://github.com/Ultraschall/ultra...cs_Jul2018.txt
@daxliniere
You're welcome
|
|
|
07-31-2018, 01:41 PM
|
#29
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I updated information about config-variables, including more info in the introduction as well as about the reccfg-config-variable, which sets the recording-format in the current project.
Code:
reccfg
The audioformat for Recording, as set in the Project Settings->Media-dialog
Only includes the format, not the individual format-settings(like bitrate, etc)
Setting them changes the recording-format, though setting some will
not update the Project Settings->Media-dialog properly (Video, GIF, AudioCD)
but will show WAV instead with the additional dialog-boxes for Video, GIF
or AudioCD added.
If you change the audioformat, it will use the last used setting for the "new" format, as set
in this project. Uses the default Reaper-settings for formats in new projects.
It is an integer.
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
Havent checked, but it might work for rendercfg and afxcfg as well.
|
|
|
08-04-2018, 04:11 AM
|
#30
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
@mespotine
Hi ! Where did you find the video processor accessible variables exposed there ?
|
|
|
08-04-2018, 04:25 AM
|
#31
|
Human being with feelings
Join Date: Sep 2009
Posts: 863
|
Mespotine - many thanks for all of this, having the API grouped by functionality is particularly helpful
|
|
|
08-04-2018, 05:23 PM
|
#32
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
@XRaym
I'm not sure, what your question is. Do you mean configvariables(if yes, which ones?), the statechunk in which the videoprocessor code is included or something else?
Edit: I think what you mean is the following: go into the IDE of the video-processor and hit the F1-key. This opens a window with all special variables and funcitons for the video-processor.
@RobU
Thanks
Yeah, especially for beginners, this grouping is a good start to know, which function does roughly what, as some functionnames are sometimes misleading.
Last edited by Meo-Ada Mespotine; 08-04-2018 at 05:58 PM.
|
|
|
08-05-2018, 06:56 AM
|
#33
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
Quote:
Edit: I think what you mean is the following: go into the IDE of the video-processor and hit the F1-key. This opens a window with all special variables and funcitons for the video-processor.
|
That was it !
Thanks we have a better formatted doc ^^
|
|
|
08-05-2018, 05:43 PM
|
#34
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I updated the API-Docs as well as the action-list and the config-variable-docs to Reaper 5.941.
I also updated the action-list-ini-file, which should be easier accessible on programming side than the actionlist exported by SWS.
|
|
|
08-07-2018, 10:04 AM
|
#35
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
I added docs to many of Lua's gfx-functions, including return-values, that exist for many of them without them being documented.
|
|
|
08-20-2018, 01:10 AM
|
#36
|
Human being with feelings
Join Date: Dec 2012
Posts: 13,334
|
Make this thread sticky please
|
|
|
08-21-2018, 03:50 AM
|
#37
|
Human being with feelings
Join Date: Jun 2015
Posts: 474
|
Amazing! Thank you very much!
That is something that I was hoping for quite a long time now as I only rarely code and almost always try and error me through the functions to find out what values are really needed or possible.
Klasse!
|
|
|
08-21-2018, 05:02 AM
|
#38
|
Human being with feelings
Join Date: Apr 2013
Location: France
Posts: 9,900
|
Hi !
Is there any way where video processor param are described ?
Here is an exemple:
Quote:
//@param3:ypos 'Y position' 0.5 -0.5 1.5 0.5 0.01
|
I was trying to make a knob from 0 to 4 with 1 as increment and 4 as default value but I get very very weird results, like a knob from 0 to 4 but with 1 as mid value... I don't get it ^^
|
|
|
08-21-2018, 04:26 PM
|
#39
|
Human being with feelings
Join Date: May 2017
Location: Leipzig
Posts: 6,630
|
@XRaym
Haven't done much on the video-processor-side, so I can't help with that one.
Aside from the help provided by Reaper, though it is quite limited, yet.
I once fumbled my way through the params-statement/function/whatever but I completely forgot everything.
@mods
Thnx for making this sticky
|
|
|
08-21-2018, 10:06 PM
|
#40
|
Human being with feelings
Join Date: Jun 2012
Posts: 2,173
|
Hi. So, I set defsendflags and it works fine throughout the session, but unless I open preferences and click ok, or apply maybe, it won't persist into the next time I open Reaper. What's that all about? Can it be forced? Have to write to Reaper.ini?
Last edited by FnA; 08-21-2018 at 10:29 PM.
|
|
|
Thread Tools |
|
Display Modes |
Linear Mode
|
Posting Rules
|
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts
HTML code is Off
|
|
|
All times are GMT -7. The time now is 08:39 PM.
|