Page de couverture (logo)
Contents
1. 6 04 002 a Name Date modified bin e AudioVolumeExample xcodeproj 02 04 2015 10 24 bil mample D e AudioYohumeExampi 23 03 2015 18 48 T libs AudioVolumeExample cpp 23 03 2015 18 48 AudioVolumeExample h 23 03 2015 18 48 i modules mn E REA amp W AudioVolumeExample sin 23 03 2015 18 48 B s M i AudioVolumeExample v12 suo 02 04 2015 15 48 tr AudioVolumeExample vcxproj 02 04 2015 13 34 E AudioVolumeExample vcxproj filters 23 03 2015 18 48 dj AudioVolumeExample vcxproj user 23 03 2015 18 48 A DOUBLE CLICK on the AUdioVolumeExample sin should open the project in Visual Studio og AudioVolumeExample Microsoft Visual Studio Express 2013 for Windows Desktop Administrator FILE EDIT VIEW PROJECT BUILD DEBUG TEAM TOOLS TEST WINDOW HELP il 2 bl ut gt Local Windows Debugger Debu v Win32 T gg g Solution Explorer vax A emn Ex AudioVolumeExample X Global Sco 1 E Search Solution Explorer Ctrl p 2 file fa Solution AudioVolumeExample 1 project 3 AudioVolumeExample h 4 AudioVolumeExample 4 b x5 External Dependencies 5 gauthoc gt oH sdk 6 Martin FLEURENT aka martignasse y 7 D annees D NG 8 brief d AudioVolumeExample h 9 Definitions of the AudioVolumeExam 16 11 Example user module to show how to 12 13 historic Now go to the menu BUILD gt Build Solution to start the compilation Sensomus2. MSG CHANGE coeffGain sdkDbToCoeff sdkGetEvtData fdrGain 1 0f sdkGetEvtData switchMute Data Multiply example Minimal math module two data inputs A and B and one output equal to A B It s an interesting module because it s totally event based all the stuff is made in the onCallBack callback Event System The module has three parameters they are defined in the onGetParamInfo function dtfInputA case 0 pParamInfo ParamType ptDataField pParamInfo Caption A pParamInfo IsInput TRUE pParamInfo IsOutput FALSE pParamInfo CallBackType ctImmediate break Notice how we set the callback type to ct Immediate on the two inputs Like that we have immediate response in onCallBack when a parameters change See how we compute the output value directly in callbacks of the inputs if Message gt message NOTIFY MSG USINE CALLBACK int paramIndex int Message gt wParam if paramIndex 0 paramIndex 1 88 Message gt lParam MSG CHANGE sdkMultEvt3 dtflnputA dtfInputB dftOutput Sensomusic SDK User Manual v1 0 Page 22 We have a simple and efficient module completely based on the event system Draw Box example With this graphic module we draw a box with the mouse after that we can zoom in out the box with the mouse wheel We look at the user interface of the module and the functionalities around it Choosing in onGetModuleInfo that pModu
3. Processing midi Messages aaa kaaa aaa asim ALIAE 25 Simple Pad examplpu sama KAANEAGG 26 a AA PA AA 26 Automation Kan Naa Aa AA aestu ab ta Seid 27 LAN REMO naaa aan ain ont 29 Pa aa AA 29 5 Usine rules for user miO Guile aisicscccssinesesescntsessaecesansucnuoensnsnenenesnnsusnsnsnsanyaiasesenaxeuosenninaddcnsasnnsten 31 Multi platform EPS 31 Usine workflow integration is rsninnenianeerssannmnnrrndenrnrerteniens 31 lici jio 31 Parameters Min Max Precision Scale Symbole 32 6 Development info s tips amp tricks 33 Parameters Or S ttIME AA AA nie ttes 33 How to update parameters in sync With time 33 Te CONCRISION ed T TTT ANA 34 Sensomusic SDK User Manual v1 0 1 Introduction The power of Usine comes from the generic way you can customize your live setup and your interface to create exactly the environment you want The core of this power is the module concept which let you patch and organize your data flow in any direction with a generic approach To optimize or extend your patches you can use the script language to make your own modules It s more CPU friendly than patching and easy because completely integrated in Usine But the SDK is the ultimate tool to extend Usine You can construct your own user module in C to create any new module you can imagine Conventions Used in this Manual This manual provides indicators to guide the user when performing procedure
4. Product 5Build to start the compilation Sensomusic SDK User Manual v1 0 Page 9 Xcode File Edit View Find Navigate Editor ES Debug Source Control Window ET Run R eoe p fy AudioVolumeExample My Mac Aud Test 3571 umeExample Succeedei g EH a NO ES Ec Ba lt Analyze OB AudioVolumeExample F v B AudioVolumeExample MAA AAHH 1 target OS X SDK 10 10 2 cs AudioVolumeExample cpp a 4 Build For gt Bam gt B0 sak 6 4 nasse gt Bil Products Build 2B 9 1 Clean 38K umeExample class to n A how to process audi n 4 3 4 Scheme gt 14 di D x 15 A tination gt ck CPP SDK 6 084 001 17 ss Create Bot 18 mis Tree Is paru 0T ne usine Hollyhock CPP SD The output log should say compile success Editor Product Debug Source Control Window Help J 1 lac AudioVolumeExample Build AudioVolumeExample Succeeded Today at 15 43 BR lt AudioVolumeExample gt h AudioVolumeExample h No Selection aaa fatile The result dylib is located in the folder Sensomusic SDK bin SDK Examples v M Sensomusic SDK 6 04 002 v O bin v 3 SDK Examples M AudioVolumeExample usr osx32 That s it you are now ready to create y OS X 10 6 Snow Leopard compatibility If you want your module to work on OSX 10 6 be aware of the fact that Apple made some changes in some low level functionality of OSX audio graphic
5. ll see a use case with the Simple Pad example later Settings Panel Parameters appear in the B tab E ofthe Settings panel But a user module can add entries in the Design tab too for settings that don t need to be exposed as real time parameters Here we can see the added entries in the Design tab for the Granulator module Granulator granulator MUS NE line line width line color To do so we just need to implement the onCreateSettings function and populate it with SDK functions to create some settings entries The onsettingsHasChanged function is implemented to be informed of a change See the Simple Pad example for an implementation Wa Parameter or Setting that is the question It s important when you construct your module to choose if a piece of data should be exposed as a parameter or a setting A setting takes less memory but is very slow in patches See Development infos tips amp tricks section for more info Graphic Canvas You want your module to have a user interface set pModuleInfo gt ModuleType mtControl Then implement onPaint and use SDK functions to draw the module interface Sensomusic SDK User Manual v1 0 Page 16 Draw Box example show a basic implementation of the onPaint callback In addition if the module has a user interface you can have access to many features e Contextual Menu e Automation Recording e Mouse events e Multi touch event Of course y
6. Back Processing audio buffers We now have two array of UsineEventPtr We want to apply some processing on the inputs and push the result on the outputs So we want to manipulate audio buffers The thing is the data of an audio parameter event is literally the audio block and the SDK provide lots of function to manipulate event directly You can find them in the Events manipulation and Events data utils sections in the API Reference Documentation The good place to do that is in the onProcess callback It s the place to do real time stuff We implement it to copy audio inputs to output and apply the gain void AudioVolumeExample onProcess for int i 0 i lt numOfAudiotInsOuts i sdkCopyEvt audioInputs i audioOutputs i sdkMultEvt1 coeffGain audioOutputs i Notice how we loop through the arrays and do some simple operations on events We don t process sample by sample but on the block of samples directly thanks to the SDK event helpers The coeffGain is computed in onCallBack by collecting the fdrGain event value and converting it from dB to coefficient Sensomusic SDK User Manual v1 0 Page 21 void AudioVolumeExample onCallBack UsineMessage Message filter only message specific to this user module if Message gt message NOTIFY MSG USINE CALLBACK Message wParam is equal to ParamIndex if Message gt wParam gt numOfAudiotInsOuts 2 amp amp Message lParam
7. CanRecord TRUE As for now the recording is limited to three float data numbers and we have to store at least two numbers per pad x and y coordinate So we are limited to one pad for the recording but if we use the third slot to store the pad index we can record any of the four pad Sensomusic SDK User Manual v1 0 Page 27 We use sdkProcessRecord in onMouseMove and sdkStopRecord in onMouseUp to tell Usine when to record data if needed MouseMove callback void SimplePadExample onMouseMove TShiftState Shift float X float Y we only want to draw when the left mouse button is down if mouseLeftButtonDown amp amp selectedPad gt 0 float posX X selectedPadOffsetX float posY Y selectedPadOffsetY updatePad selectedPad std min 1 0f std max posX 0 0f std min 1 0f std max posY 0 0f try catch std exception amp e sdkRepaintPanel sdkProcessRecord TPrecision selectedPad posX posY MouseUp callback void SimplePadExample onMouseUp TMouseButton Button TShiftState Shift float X float Y mouseLeftButtonDown FALSE selectedPad 1 try sdkStopRecord PUN std exception amp e Note how we encapsulate our call to those functions in a try catch block as we don t want to propagate any exception In case of errors the recording won t be effective but our module won t report errors at Usine level We now have to implement the o
8. Move TShiftState Shift float X float Y we only want to draw when the left mouse button is down if mouseLeftButtonDown collecte mouse pos in case of zoom lastMousePos x X lastMousePos y Y updateBox std min 1 0f std max X 0 0f std min 1 0f std max Y 0 0f We update the bottom right corner of the box with the new mouse coordinates while left button is down Here we just store the state of the left button void DrawBoxExample onMouseUp TMouseButton Button TShiftState Shift float X float Y mouseLeftButtonDown FALSE With the mouse wheel we apply the zoom to the box void DrawBoxExample onMouseWheel TShiftState Shift int WheelDelta WheelDelta gt 0 boxScale 1 1f boxScale 0 9f apply the scale boxCoords left boxCoords left lastMousePos x boxScale lastMousePos x boxCoords top boxCoords top lastMousePos y boxScale lastMousePos y boxCoords bottom boxCoords bottom lastMousePos y boxScale lastMousePos y boxCoords right boxCoords right lastMousePos x boxScale lastMousePos x limit to canvas bounds boxCoords left std min 1 0f std max boxCoords left 0 0f boxCoords top std min 1 0f std max boxCoords top 0 0f boxCoords bottom std min 1 0f std max boxCoords bottom 0 0f boxCoords right std min 1 0f std max boxCoords right 0 0f We use the 1astMousePos collected in onMouseMove to center the z
9. OfOptFaders NumOfFaders result NumOfFaders OPT FADERS SHIFT return result The onAfterQuery callback isn t needed in the Matrix module but can be used to initialize some stuff Event System As an extension of Usine the Module can listen to the event system of the application The onCallBack function is a very important procedure to implement in a module It not only let us receive some Usine messages but we use it also to be informed of change on parameters of the module Parameters are defined in oncetParamInfo with a ParamIndex This unique index is contained in the UsineMessage wParam to identify the Parameter concerned by the callback The UsineMessage 1Param is the type of event mouse click mouse move value change void DrawBoxExample onCallBack UsineMessage Message filter only message specific to this user module and type MS_CHANGE if Message gt message NOTIFY_MSG_USINE_CALLBACK amp amp Message gt lParam MSG_CHANGE WParam contains the Param Number Sensomusic SDK User Manual v1 0 Page 14 switch Message gt wParam Erase trajectory button input case 0 eraseBox break randomize button input case 1 onRandomize break Real time Audio and Data process Activated by default if you don t need it you can deactivate it with ModuleInfo DontProcess TRUE in onGetModuleInfo If activated the onProcess function is called by Usine in sync w
10. ally we use this procedure to directly respond to a parameter change but we can also just collect info to be processed somewhere has we don t have time reference here The onProcess callback e Is called in sync with audio blocks it s the streaming flow of Usine and precisely timed e The granularity depends of the buffersize samplerate of the audio driver and the buffersize of usine e It s where we naturally process audio blocs but it s also where you can do other thing in sync with the time e It s literally the time slice of the Usine engine Consequences e Using sdkSetEvtValue on the same parameter in a while or a for loop is irrelevant e The best way to do some parameters change in sync with time or an ordered sequence of parameter changes is to do it in the onProcess callback Sensomusic SDK User Manual v1 0 Page 33 7 Conclusion This document gives you a good overview of the SDK architecture and how to produce simple modules As you ll practice and go deeper you ll see that possibilities are endless We do our best to open the power of Usine through the SDK and with this tool you can easly customize Usine to suit your need It s up to you now to amaze us with your creation If you have any feedback tell us on the SDK section of the Sensomusic forums Happy coding Martin Fleurent amp the Sensomusic Team Sensomusic SDK User Manual v1 0 Page 34
11. assign handles to your module parameters void onSetEventAddress int ParamIndex UsineEventPtr pEvent needed by usine to inform your module about parameters actions void onCallBack UsineMessage Message Some are needed depending on the info s you put in the pModuleInfo structure Let s take an example you want your module to have a GUI you activate this feature by choosing pModuleInfo ModuleType mtControl in onGetModuleInfo Now your modules has a graphic canvas it s up to you to draw the module GUI so you have to implement the onPaint callback needed by Usine to draw the module canvas if it is of type mtControl void onPaint We use some functions provided by the SDK here like sdkDrawLine or sdkFillText to populate the canvas In addition you can receive mouse events of this canvas by implementing those callbacks Sensomusic SDK User Manual v1 0 Page 11 optional if the module has a canvas ModuleType mtControl those callbacks let you know about mouse events on it void onMouseMove TShiftState Shift float X float Y void onMouseDown TMouseButton MouseButton TShiftState Shift float X float Y void onMouseUp TMouseButton MouseButton TShiftState Shift float X float Y Some of those callbacks are not connected to special features they just let you do things when something specific happen Usine call it when the Usine Size change void onBlocSizeChange int BlocSize Usine call i
12. esign tab setting panel void SimplePadExample onCreateSettings we had our user section in the edit layout panel sdkAddSettingLineCaption DESIGN TAB NAME pad Sensomusic SDK User Manual v1 0 Page 26 sdkAddSettingLineColor DESIGN TAB NAME amp colorPad color sdkAddSettingLineInteger DESIGN TAB NAME amp sizePad size 1 30 scLinear px 20 Here is the result in Usine interface 1 rack LO Q simple pad example simple pad exampl x Bre patch O pad simple pad example color size global edit enabled on top opacity blur softness background Note how entries appear in the order they are implemented and how we organize our setting by regrouping them under an explicit caption We also implement the onSettingsHasChanged just to be sure the Graphic Canvas is updated immediately when a setting change Callback which indicate that the user has changed someting in the layout You ll probably need to redreaw void SimplePadExample onSettingsHasChanged Ask to repaint the module sdkRepaintPanel We don t have anything else to do here because the colorPad and sizePad variable are directly used in the onPaint callback when we draw the Canvas content Automation Recording To use the Automation Recording feature we have to activate it in the onGetModuleInfo callback This let Usine to be informed to check our module when the record button is pressed pModuleInfo gt
13. for complete description of each function e Graphic canvas e Usine Core infos and services e Automation recording e Usine Paths getters Settings options e Files utils e Contextual Menu commands e Audio Files manipulation e Lan Remote request e Math utils e Events manipulation e Trace functions e Events data utils e Dialog popup e Parameters setters e Module child window e Audio Channels query e Utils and Helpers E Naming convention is here to help All these utility functions have a name beginning by sdk It provides easy filtering with code complexion Sensomusic SDK User Manual v1 0 Page 19 4 Understanding SDK exampks Five module examples are provided to show some of the features of the SDK and the way to use them The best way to read this part is in front of the sources opened in your IDE Studying those examples are a good way to learn how the SDK work and how to make good modules It s also a perfect base to start with and extends them if you don t feel to start from scratch 4 At start don t start from scratch Starting from an existing project exempt you from having to fully configure it Let s go exploring them and learn how to code our own modules Audio Volume example It s a simple audio gain module with a query system to set the number of channels at creation It also shows how to process audio buffers It s a good base for any audio processing module that needs to imp
14. ic SDK User Manual v1 0 Page 7 og AudioVolumeExample Microsoft Visual Studio Express 2013 for Windows Desktop Administrator FILE EDIT VIEW PROJECT BUILD DEBUG TEAM TOOLS TEST WINDOW HELP B S uM Build Solution F7 32 Rebuild Solution Ctrl Alt F7 Solution Explorer m Clean Solution Global Scc T 5 i d o eae Run Code Analysis on Solution At Search Solution Explorer Ctrl fg Solution AudioVolumeExampl 4 AudioVolumeExample Project Only b Configuration Manager b gg External Dependencies Co sd b 35 sdk omer martignasse b AudioVolumeExample cpp 8 brief gt B AudioVolumeExample h 9 Definitions of the AudioVolumeExam an ae The output log should say compile succeeded Show output from Build x t 1 gt AudioVolumeExample cpp 1 gt Creating library C temp VC Debug AudioVolumeExample AudioVolumeExample lib 1 AudioVolumeExample vcxproj gt C temp VC Debug AudioVolumeExample AudioVolumeE 1 C temp VC Debug AudioVolumeExample AudioVolumeExample usr win32 1 gt 1 File s copied Build 1 succeeded failed up to date skipped If you can t locate the output windows go to the menu VIEW gt Output to show it The result user module which is in fact a dll is located in the folder Sensomusic SDK bin SDK Examples Computer Datas D Usine Sensomusic SDK6 04 002 bin SDK Examples Organize v Inc
15. is case there is no difference if we are storing for preset or for patch workspace Sensomusic SDK User Manual v1 0 Page 30 5 Usine ruks for user modubs Making module with the SDK is one thing making good modules reusable and sharable with other is another In this chapter we ll see an overview of subject to help you in that way Multi platform Due to the Multi platform nature of Usine and so the SDK it s very important to develop your module with that in mind The module output binary produced by the compilation is a Dynamic library Usine use special name extension to identify the module target platform Here is the naming convention PC MAC Can be compiled for x86 or x64 targets Name extension for x86 target usr osx32 Name extension for x86 target usr win32 Future implementation Name extension for x64 target usr win64 Name extension for x64 target usr osx64 The SDK itself is platform agnostic but the way you code and the dependencies you use in your module can make the task extremely complex Try to use as much as possible the STL library as it is well integrated in most IDE At some point you may need some external library to do the job Here you have to think about multi platform and choose carefully your dependencies Usine workflow integration A module can integrate lots of features Some can be added alone and some are inter dependent As a template try to mimic modules of the Usine di
16. ith the audio engine It s where you can do some real time calculations In the onProcess function is executed each audio parameter contains an array of audio samples dimensioned to the BlockSize of the Usine engine You can easily take inputs audio block make an operation and copy the result on the outputs The Audio Volume example shows a simple event operation Be careful The onProcess is called from the audio thread at each audio tick of the audio engine so every BlocSize samples Keep it optimized and avoid any memory allocation here pre allocate them at initialization time Chunk System A chunk is a memory block used to store some binary data Usine store chunks in patch and workspace files and use them to store restore presets In a module parameters are automatically stored except if TParamInfo DontSave is set to TRUE Parameters are automatically stored in presets if TParamInfo IsStoredInPreset is set to TRUE But sometime you need to store internal values or extra data and you use the chunk for this Sensomusic SDK User Manual v1 0 Page 15 You use the chunk system by implementing three callbacks They are called by Usine when storing restoring patch workspace or presets e onGetChunkLen return the chunk length estimation e onGetChunk Provide a chunk handle to fill with the extra data you need to store e onSetChunk provide a chunk handle filled by Usine to restore your data into the module We
17. je main Sudu initialisation cre4 procedure init begin Input CreatePa uine Hollyhock SDK User Manual v1 By Martin Fleurent 1 Table of Contents Ma LL AA AA ra een AE AA AA AA AA AA 4 Conventions Used un this MAnva s nanas umateunasucus 4 IS CAT sr eec AA nent terne AA AA 6 AA AA AA 6 MAAC AA AA 9 SDK DASICS man AA a ana 11 A Module is made of Darts iuscusciscii iiber KAEN 11 Mod le functionalities sssini eaaa 12 AA eee ace eee en 13 Event Sy SG eds amemennbien etant en 14 Real time Audio and Data BIOGDCGSS eai aan mena pupa OE ME 15 Chunk SNS TOM dedans bud linca paie 15 Seanas A c c lesa iere DE LED e LE ELE MI UU 16 Graphic Canvas PAA AD AA AA PAP ee S du 16 Contextual Menit acti tia atium NBA a 17 Automaton PCO NG a ase ta esse ANN ANAN 17 RE AA A ereree 18 MONEY aaa AA AA E 18 Da daa AA AA 18 LAN REMULLA AANI de 18 Utilities LU Ca NG AA 19 Understanding SDK examples terna cenis cu dada inc caida e LU rta EL ERROR 20 Audio Volume examplg ieseeeiraixoncaciii nrc conus nbn Eco ncn CU ta niis edi 20 The guery Syste assie AA AA AA AA NA AA AA 20 Pr c ssing aud AA AA nne a pa Mus tani rut 21 Data Multiply example race maman niu CU cwn 22 Event System AA i tmd eb 22 Draw Box example aaa AKA AKA BANGKA BAKA 23 Se SR AA PAP 23 Sensomusic SDK User Manual v1 0 MOUSE AUS DESERT DR A R O 23 Randomize Cossus cunt PA AAAH 25 Contextual MEN AA AA irs 25 Midi Transpose ramp Gua GAGA 25
18. leInfo gt ModuleType mtControl activate your module user interface We now have to draw the module and we can collect mouse actions to draw the box in real time Finally we add two commands in the contextual menu to reset and randomize the box Graphic interface Implement onPaint to draw the module interface here a simple rectangle void DrawBoxExample onPaint we check the box top value to see if there is something to draw if boxCoords top gt 0 sdkFillRect boxCoords colorBox 0 colorBox 0 i See how we keep this very simple and just draw with the boxCoords we compute elsewhere in the Mouse events callbacks precisely Mouse events We implement three mouse callbacks onMouseMove onMouseDown onMouseUp and onMouseWheel to collect mouse info s and update the box void DrawBoxExample onMouseDown TMouseButton Button TShiftState Shift float X float Y if Button mbLeft float left std min 1 0f std max X 0 0f float top std min 1 0f std max Y 0 0f boxCoords left left boxCoords top top boxCoords bottom top boxCoords right left we store the state of the left button mouseLeftButtonDown TRUE Sensomusic SDK User Manual v1 0 Page 23 At mouse down we limit the mouse input to 0 1 the size of the graphic canvas We use the mouse coordinates to initialize our box We store the left button state and the last mouse move void DrawBoxExample onMouse
19. lement the multi channel query The query system Using the query system to choose how many audio channels a module has to deal with is a common case the SDK provides some helpers and this module show how to use them We activate the query system in onGetModuleInfo by filling the appropriate members of the pModuleInfo structure query for multi channels if pMasterInfo nullptr pModuleInfo gt QueryString sdkGetAudioQueryTitle pModuleInfo QueryListValues sdkGetAudioQueryChannelList pModuleInfo gt QueryDefaultIdx 1 We have to implement onGetNumberOfParams to tell Usine the total numbers of parameters the module has based on the user choice Get total parameters number of the module int AudioVolumeExample onGetNumberOfParams int queryIndex Sensomusic SDK User Manual v1 0 Page 20 int result 0 this queryIndex queryIndex numOfAudiotInsOuts sdkGetAudioQueryToNbChannels queryIndex we want 1 in 1 out per channels result numOfAudiotInsOuts 2 numOfParamAfterAudiotInOut return result sdkGetAudioQueryToNbChannels provides us how many channels we have to implement In this example we don t need to implement onAfterQuery but it s a good place to do stuff just after the popup Ei Many Audio parameters Study how we manage Audio parameters in and out with two array of UsineEventPtr and how we map them with ParamIndex in onGetParamInfo onSetEventAddress and onCall
20. lude in library Share with Burn New folder 4 Sensomusic SDK 6 04 002 Name 4 L bin SDK Examples gt examples gt libs D modules d sdk AudioVolumeExample usr win32 That s it you are now ready to create you own module Sensomusic SDK User Manual v1 0 Page 8 MAC You only need Xcode to make a user module if needed download it from the AppStore and install it Now open the AudioVolumeExample xcodeproj module project and compile it to verify that all is ok w Sensomusic SDK 6 04 002 gt M bin v 3 examples v M AudioVolume AudioVolumeExample cpp h AudioVolumeExample h AudioVolumeExample sin AudioVolumeExample vcxproj AudioVolumeExample vcxproj filters AudioVolumeExample vcxproj user B AudioVolumeExample xcodeproj gt 3 DataMultiply A DOUBLE CLICK on the AUdioVolumeExample xcodeproj should open the project in Xcode Xcode File Edit View Find Navigate Editor Product Debug Source Control Window eoe gt fy AudioVolumeExample My Mac O aQ A B AudioVolumeExample 1 target OS X SDK 10 10 AudioVolumeExample cpp Ih AudioVolumeExample h gt D sdk gt P Products BH Ow WW No AudioVolumeExample Clean AudioVolumeExample Succeede lt D AudioVolumeExample h AudioVolumeExample file AudioVolumeExample h author Martin FLEURENT aka martignasse brief Now go to the menu
21. nSetRecordedValue callback which is called by Usine to provide replay data to the module recording void SimplePadExample onSetRecordedValue TPrecision X TPrecision Y TPrecision Z 1 updatePad int X Y Z Note that names for the callback parameters are just convention we use the first data for the pad index and the two other for the pad coordinates Sensomusic SDK User Manual v1 0 Page 28 We update the according pad coordinates and voila LAN Remote This feature is enabled at parameter level by setting pParamInfo IsShared to TRUE in onGetParamInfo for each parameters we want to be shared Here we want to share the two arrays arrPosX and arrPosY that represent the four pad coordinates After that we just have to tell Usine when we want those parameters to be updated on the LAN We do this by using sdkNeedRemoteUpdate with the paramIndex of the parameter Here it s implemented in the updatePad method and onSetChunk callback as they are where we update the pad coordinates update a pad coordinates void SimplePadExample updatePad int padIndex float x float y posTab padIndex x x posTab padIndex y y sdkSetEvtArrayData arrPosX padindex x sdkSetEvtArrayData arrPosY padindex 1 0f y sdkNeedRemoteUpdate 1 sdkNeedRemoteUpdate 2 Ask to repaint the module sdkRepaintPanel 1 and 2 are the paramIndex of the arrPosX and arrPosY array events Chunk system We have no inp
22. o use v MM Sensomusic SDK 6 04 002 gt DM bin gt M examples gt M libs Licence txt EM modules Release Notes txt PO sdk v v e The bin folder is where ends up all compiled binaries e The examples folder provides 5 simple User Modules they are made to learn the basics and we ll see them in details in this manual They are also a good starting point for your own modules as they cover usual needs in term of modules types e The libs folder is for dependencies in case a module needs an external library e The modules folder contains more than 20 complex modules and distributed with Usine like Matrix and devices They are good examples of how far you can go and to acquire deep understanding of the SDK e The SDK folder contains files with declarations and the module wrapper In order to compile a module you ll need a compiler we provide project for Visual Studio on PC and Xcode on Mac Let s start by opening the project of an example module to check if all is correctly installed PC You only need to have Visual Studio installed to make a user module If needed download and install it version 2012 or later We ll now open the AudioVolumeExample module project and compile it to verify that all is ok Sensomusic SDK User Manual v1 0 Page 6 Computer Datas D Usine Sensomusic SDK 6 04 002 examples AudioVolume gt Organize Mj Open Burn New folder 4 Sensomusic SDK
23. of parameters of the module depending of the query result e The second one onAfterQuery is called after the query pop up is closed It let you do some things depending of the query choice A typical use of the query system is in Audio modules it let the user chose the Multi channels characteristic of the module The SDK provide some utilities functions for that we ll see them in the Audio Volume example e Number o 5 e Number of presets cancel cancel cancel But the query system can be used for many things let s look at the Matrix Display amp Set module implementation In the onGetModuleInfo callback pModuleInfo receive the options for the query popup In this case it s to ask the user how many faders to show pModuleInfo QueryString Number of faders pModuleInfo QueryListValues no fader 16 faders 32 faders 64 faders 128 faders pModuleInfo gt QueryDefaultIdx 1 Sensomusic SDK User Manual v1 0 Page 13 The onGetNumberOfParams callback inform the module of the query response index and let compute the total number of parameters from it Get total parameters number of the module int TMatrixModule onGetNumberOfParams int queryIndex int NumOfFaders 0 int result 0 switch queryIndex case 1 NumOfFaders break case 2 NumOfFaders break case 3 NumOfFaders break case 4 NumOfFaders break default break 16 328 64 128 m num
24. oom under the mouse position Sensomusic SDK User Manual v1 0 Page 24 Randomize Here we implement the onRandomize callback to produce a randomized box usine randomize void DrawBoxExample onRandomize boxCoords left float rand float RAND MAX boxCoords right float rand float RAND MAX boxCoords top float rand float RAND_MAX boxCoords bottom float rand float RAND MAX Ask to repaint the module sdkRepaintPanel Note that we also call this function internally from the onCallback callback for the btnRandomize parameter Contextual menu Adding contextual commands is as simple as implementing the onCreateCommands callback void DrawBoxExample onCreateCommands sdkAddCommandSeparator cmd edit sdkAddCommand cmd reset 0 sdkAddCommand cmd randomize 1 Inside we add commands and link them to a callback index Here it corresponds to the same actions that the two inputs parameters reset and randomize Midi Transpose example It s a good base module for some Midi hacking We have an input fader to tweak the pitch and two midi parameters one for the input and one for the output We do the midi stuff in onProcess callback to be in sync with the audio engine Processing midi messages We use the onProcess callback to copy the in to the out and apply a transposition based on the pitch collected with sdkGetEvtData Midi parameter event contain one o
25. ou implement them only if needed Contextual Menu If your module has an interface pModuleInfo gt ModuleType mtControl it has a contextual menu You can use it to place some rapid access commands like reset or randomize The added entries reset and randomize of the Draw Box example contextual menu draw box example h or Xx patc Lo find in patch draw box example rename reset randomize To do so implement the onCreateCommands callback and create some menu entries You can add a menu separator with sdkAddCommandSeparator sdkAddCommand add a named entry and fire a callback message with the index provided when the command is clicked If you provide the index of an existing parameter you have a direct link to it Or you can put a free index and do what you want in the callback Automation Recording This feature is available only if the module has a graphic canvas You ll also need Mouse or multi touch events to feed recording data Sensomusic SDK User Manual v1 0 Page 17 It let the user module to respond to the Automation Record rs and record up to three distinct data s in automation curves You activate the Automation Recording if ModuleInfo CanRecord is set to TRUE in onGetModuleInfo Then use sdkStopRecord and sdkProcessRecord in your code to record the automation Implement the onSetRecordedValue function to update the module from the replay information The Simple Pad Example will show us how
26. r more UsineMidiCode in an array Sensomusic SDK User Manual v1 0 Page 25 void MidiTransposeExampleExample onProcess int sizeMidiIn sdkGetEvtSize midiIn sdkSetEvtSize midiOut 0 if sizeMidiln gt sdkCopyEvt midiln midiOut int pitch int sdkGetEvtData fdrPitch for int i 0 i lt sizeMidiIn i UsineMidiCode code sdkGetEvtArrayMidi midiOut i if code Msg MIDI NOTEON code Msg MIDI NOTEOFF code Datal std min 127 std max 0 int code Datal pitch sdkSetEvtArrayMidi midiOut i code midiln and midiOut are the events of the midi parameters They contain on or more UsineMidicode in sync with the Audio Engine The result is a module that s transposes Midi notes in real time Note that we don t use the Event System and don t need to implement onCallBack Simple Pad example Let see another graphical module This time we have 4 pads we can manipulate with the Mouse events To store the pads position we use the chunk system In addition we implement the Automation Record LAN Remote system and add some settings in the design panel We don t focus on the Graphic canvas or the Mouse events this time as we have lot of other feature to study Settings Panel We want to let the user choose the color and the size of the pads but we don t to expose this as parameters so we implement the onCreateSettings callback create user defined layout options in the d
27. s It could be necessary to compile the project with XCode 3 2 6 on a MAC with OS X 10 6 installed as the OS Sensomusic SDK User Manual v1 0 Page 10 3 SDK basics This is an overview of what a User module is made of We begin to speak about code without going too deeply If you want further info on a function the API Reference Documentation describes exactly what each function does T construct a module the SDK offer you a simple but powerful approach Two global functions one to instantiate and the second to destroy your module AUserModuleBase class to derive from providing complete communication with Usine and all the necessary stuff to customize your module behavior In addition this base class provides many utility functions to help you integrate your data in the module So your module is contained in one class derived from the UserModuleBase class By implementing and customizing certain part of this base class you can construct the module you want A Module is made of parts It s a brunch of callbacks used by Usine to communicate with your module Some are mandatory and you must implement them in your module Let see them needed by usine to obtain your module characteristics void onGetModuleInfo MasterInfo pMasterInfo Moduleinfo pModuleInfo needed by usine to obtain parameters characteristics of your module void onGetParamInfo int ParamIndex TParamInfo pParamInfo needed by usine to
28. s and when pointing out important key concepts terms or actions Indicates a key term or concept such a Mouse events Visual Studio or Xcode Italics indicate a location path to navigate such as Library Audio FX EC Icons such as the gear to the left help guide the user to locate the similar icon available on the Usine Interface Screenshots such as the one below is used to help the user to perform similar action or to locate some informations in the Developpment Environment Editor Product Debug Source Control Window Help lac AudioVolumeExample Build AudioVolumeExample Succeeded Today at 15 43 EM AudioVolumeExample gt h AudioVolumeExample h No Selection 1 f Hatile Menu Product 5Build indicates the menu path to perform an action in the Developpment Environment Links to Web content like Sensomusic site or to other part of the document like the Draw Box example Sensomusic SDK User Manual v1 0 Page 4 Code reference like a functionName or variables in a paragraph Code snippets are formatted as follow example of code snippet void onGetModuleInfo MasterInfo pMasterInfo ModuleInfo pModuleInfo Sensomusic SDK User Manual v1 0 Page 5 2 Installation Usine is multi platform MAC PC so is the SDK We have made our best to follow the Write once compile anywhere philosophy The SDK is provided as a zipped folder unzip it where you want and it s ready t
29. stribution in term of ergonomics and feature integration For example if your module has a canvas it has also a contextual menu and you should can populate it with quick access actions that are not on the canvas like reset or randomize Translation Make your module with multiple languages is important to help adoption Sensomusic SDK User Manual v1 0 Page 31 The default language in Usine is English and your module should implement it By convention in Usine only the Contextual menu is translated it means that parameters and settings captions in the patch and settings panels stay in English Usine do the job for you and try to translate Contextual Menu captions when needed but you have to prepare stuff to make it clean You can check in the Usine Distrib Resources Lang folder to see already existing expression handle and use it in priority If you need to add some handle put it in your module and Usine will build them automatically in the languages files thus ready to be translated Parameters Min Max Precision Scale Symbol The default Min Max is between 0 and 1 and should be prioritized until it makes sense to use another one Wa A good example the HSLA Color module The Hue parameter is between 0 and 12 because there are 12 convenient combinations of primary colors on the Hue wheel one each 30 degrees The Luminance parameter is between 0 and 2 because at 0 you have a black at 2 you have a white and at 1 yo
30. t when the SampleRate change void onSampleRateChange double SampleRate They are optional and you implement them only if you need them like adjusting a DSP algorithm to the sample rate So to resume by filling the ModuleInfo structure in onGetModuleInfo and implementing some callbacks you decide what your module can do and choose by all the functionalities offered by the SDK Module functionalities Modules are deeply integrated in Usine It means lots of features in order to comply with ergonomic and modularity of Usine workflow Those features are organized by themes as follow e Query System e Contextual Menu e Event System e Automation Recording e Real time Audio and Data process e Preset and Randomize e Chunk System e Mouse Events e Settings Panel e Multi touch Events e Graphic Canvas e LAN Remote Most of the time you only need some of them to do the job but you ll have to take care about which are necessary for a good Usine integration Contextual Menu Settings chunk Sensomusic SDK User Manual v1 0 Page 12 Query system The Query System let you to popup a choice list at module creation You can then adapt your module from the user choice To activate it for a module implement ModuleInfo QueryString and ModuleInfo QueryListValues in onGetModuleInfo Two callbacks can be implemented to react to the user choice e The first on onGetNumberOfParams is called by Usine to obtain the number
31. to do this Randomize Usine can call the onRandomize callback to tell the module to randomize itself If it has any sense to your module you should implement it to make the module Global Randomize aware See the Draw Box Example for an implementation Mouse events If your module has an interface pModuleInfo ModuleType mtControl and if you are interested in mouse events implement those three callbacks to collect the mouse activity onMouseMove onMouseDown onMouseUp onMouseWheel Multi touch events If your module has an interface pModuleInfo ModuleType mtControl andif you are interested in multi touch events implement those three callbacks to collect the mouse activity onMouseMoveMultiProc onMouseDownMultiProc onMouseUpMultiProc LAN Remote A module can be shared with other Usine instance running on a LAN network It s the LAN Remote feature and your module can share any parameter Sensomusic SDK User Manual v1 0 Page 18 A parameter is shared if ParamInfo IsShared is set to TRUE in onGetParamInfo Use sdkNeedRemot eUpdate with the paramIndex of a parameter to tell Usine to update this parameter on LAN Remote clients The Simple Pad Example will show us how to do this Utilities functions It s a huge part of the SDK All those functions can be grouped by type of functionalities and data they use Here is a list of the type of utilities provided by the SDK Check the API Reference Documentation
32. u have the plain color A Parameter scale can be one of three types Linear Logarithmic and Exponential Symbols for parameters are pure visual helpers and have no computing implication But Usine use some convention and your module should follow them Usine Rules for Values Scale and Symbol Type of value Min Max Precision Scale Symbol Pixel 0 gt 100 X XXX log pix Gain 80 gt 12 X X exp dB Frequencies 50 gt 20000 integer float log Hz Pitch 48 gt 48 integer float linear halftone Sensomusic SDK User Manual v1 0 Page 32 6 Development infos tips amp tricks This chapter covers various subjects with info s to help you with common cases you ll encounter during module development Parameters or Settings Parameters are clearly implemented with real time in mind They contain the data your module has to process or deal with Settings are more for UI settings or behavior setup Even if they can be connected they are accessible in extended mode of the module they are not made to be heavily manipulated at real time like parameters How to update parameters in sync with time Parameters e They are containers for some pieces of data e There is no assumption of the use you make of this data for logic for audio It s just numbers The onCallback callback e Is called when a parameter data change it s the event flow of Usine and is completely time independent e Gener
33. ut parameters reflecting pads coordinates so Usine won t take care of storing them for us If we want our module to restore pads position when loading a patch or a workspace and if we want to be able to recall presets of pads positions the module need to store the pads coordinates We ll use the Chunk system for this We already have the data stored internally in the posTab variable We just have to copy the content into the chunk in onGetChunk and update it from the chunk in onsetChunk compute the lentgh of the chunk string int SimplePadExample onGetChunkLen LongBool Preset Sensomusic SDK User Manual v1 0 Page 29 compute the chunk string lentgh to save points coords of pads int ChunkLen sizeof TPointF PAD OBJ MAX return ChunkLen store module datas in the chunk string void SimplePadExample onGetChunk void chunk LongBool Preset copy points coords array into the chunk memcpy chunk amp posTab sizeof TPointF PAD OBJ MAX restore module datas from the chunk string void SimplePadExample onSetChunk const void chunk int sizeInBytes LongBool Preset copy points coords array from the chunk memcpy amp posTab chunk sizeof TPointF PAD OBJ MAX for int i 0 i PAD OBJ MAX i sdkSetEvtArrayData arrPosX i posTab i x sdkSetEvtArrayData arrPosY i 1 0f posTab i y sdkNeedRemoteUpdate 1 sdkNeedRemoteUpdate 2 sdkRepaintPanel In th
Download Pdf Manuals
Related Search