Home

Start of SoundMexPro manual

1. 10 SineGenerator Sine generator that plays an online generated sine signal A slider is shown that allows realtime changing of the sine frequency This example uses a MATLAB script plugin in the time domain 11 Dynamic Bandpass Example showing how to implement an adjustable bandpass filter using a realtime MATLAB script plugins in the frequency domain The center frequency of the bandpass can be adjusted with a slider 12 BekesyTracking Bekesy Tracking example using a MATLAB script plugin 20 VST Examples vst_conv m Shows usage of the fast convolution VST plugin shipped with SoundMexPro 20 VST Examples vst_equalizer m Shows usage real and complex equalizer VST plugin shipped with SoundMexPro 20 VST Examples vst_hetero_dyning m Shows usage of the hetero dyning VST plugin shipped with SoundMexPro o SoundMexPro documentation 24 20 VST Examples vst_visualize m Shows usage of the visualization VST plugin shipped with SoundMexPro 50 Compiled Script Plugin Example How to example for creating and using compiled MATLAB script plugins in compiled applications 51 SoundMexProLoader Example Example script for using the SoundDllProLoader using SoundMexPro without MATLAB 52 C API Example Source code snippet in C demonstrating the SoundMexPro API usage of the SoundDIIPro dll in your own code See also the separate documentation SoundMexPro_Interface_De
2. enable debugsaving command debugsave In general you can use an unlimited number of virtual tracks and connect an unlimited number of tracks to each output channel however it depends on the performance of your computer and number of used plugins and their individual computing time how many tracks you can use without dropouts xruns 3 3 Audio data in SoundMexPro files and vectors SoundMexPro supports loading of audio data in two different ways Command loadmem with this command audio data can be loaded directly from MATLAB vectors to SoundMexPro The data have to be aligned as one column per audio channel and have to be scaled between 1 and 1 When loading vectors the data are copied within SoundMexPro Otherwise every change to a vector from MATLAB during playback would crash the application But this means that all audio data are resident in memory twice Thus whenever feasible the loadfile should be preferred Command loadfile using this command SoundMexPro reads audio data on the fly i e it does not load the complete file to memory but performs a buffered read during playback Therefore this method consumes less memory than loadmem However since the data are read during playback it is highly recommended not to load files from network drives The commands loadfile and loadmem have a huge number of optional parameters including gain loops ramps crossfades bui
3. Parameter This section may contain parameter names of the plugin as fields All values must be between o o and 1 0 All contained parameters are set to the specified values Example file Settings filename bin HtVSTGain dll type master input 0 1 output 2 3 position 1 Program program lin programname myname Parameter gain 020 1 gain 120 3 ify SoundMexPro documentation 35 The command vststore stores all available values to a configuration file 7 2 3 VST plugin editor The command vstedit shows a GUI editor for changing parameter values and programs on runtime VSTPluginEditor HtVSTEqualizer Equalizer H6rTech E Settings Programs No Name 000 enabled 001 visible If the plugin contains a user defined editor this will be shown otherwise a native parameter editor as shown in Figure 14 will appear Click on the sliders blue grey respectively at the right of each parameter line and move the mouse to change a value 8 ASIO Direct Monitoring ADM With version 2 of the ASIO interface Steinberg introduced the so called ASIO Direct Monitoring ADM ADM is intended to monitor one or more inputs on one or more output channels with ultra low latency by copying the input data directly to the output within the soundcard buffers itself This guarantees minimum latency but this mode does not pass the data to any ASIO application such as SoundMexPro at all Therefore you c
4. data boxes in the tracks indicate that all tracks may be filled with different data independently files and vectors may be mixed The command start starts the signal output In the example the output will start with a sum of file 1 and vector 2 on sound card channel o a sum of and file 4 file 5 and file 7 on sound card channel 5 and with vector 5 on sound card channel 6 The output proceeds as if a virtual playback cursor shown as dotted line in would run parallel through all tracks However this picture does not fit exactly if loops are used for particular audio data But the picture is correct again if you imaginary copy the audio data to be looped n times into the corresponding track The example above shows the general strategy to find the appropriate configuration of SoundMexPro for a particular task Determine how many independent channels i e soundcard outputs speakers you need Specify this number of channels in argument output with respect to the real hardware channels of your sound card you want to use Determine the total number of independent tracks i e sound data you need at the same time in parallel Specify this number of tracks in the track argument of command init If you don t need any mixing then omit the track argument one track for each channel Ne SoundMexPro documentation 13 will be created with
5. plugin as a track plugin or as a recording plugin Master plugins run on device output channels i e after mixing down tracks to device channels whereas track plugins apply processing to virtual output tracks Recording plugins type input are processing the recorded data Figure 2 in chapter 3 2 shows the different types in the SoundMexPro processing scheme Note you can connect only identical types of SoundMexPro channel to a plugin of a particular type A track plugin for example always reads from SoundMexPro tracks and writes the processed data to SoundMexPro tracks cross linking is not possible with VST plugins You have to use the commands trackmap and iostatus to change the routing within SoundMexPro To avoid ambiguous names the following definitions are used in this paragraph input input channel of the plugin output output channel of the plugin SoundMexPro channel a SoundMexPro output channel input channel or track The descriptions below are identical all types of VST plugins in SoundMexPro therefore we always use SoundMexPro channel pe SoundMexPro documentation 30 A VST plugin is loaded using the command vstload The parameters of the command define the O configuration the routing of the plugin parameter type specifies how to use the plugin as master track or input plugin parameter input specifies which So
6. Example for occurrence and handling of asynchronous errors t 09a vst simple m Simple example using a VST plugin as described in a SoundMexPro documentation 23 chapter 7 2 1 t_ogb_vst_artificial m Sophisticated artificial plugin example using fantasy data and a gain plugin to demonstrate how data are mapped routed through the VST Host of SoundMexPro t ooc vst gain m Simple plugin example using a VST plugin to change the output gain on the fly t ood vst recursion m Example for the demonstration of recurse wiring within VST plugins t 10 adm m Basic example for the usage of ASIO direct monitoring adm t 11a file2file m Tutorial for file to file operation 5 2 The SoundMexPro Examples Some advanced examples implementing common tasks are located in subdirectories in the examples subdirectory of SoundMexPro Directory name filename Description 01 Adjustable SNR This example shows how to play a tone and a noise signal on the same hardware output channels using multiple tracks A slider is used to adjust the SNR on the fly by adjusting the volume of the tone 02 Pair Comparison Two variants of a signal one of them bandpass filtered are loaded to different tracks Button clicks do a cross fade between the two variants to do a smooth transition from one signal to the other User may switch back and forth and select a winner of the comparison
7. If parameter is set to 1 default is 0 all audio data segments that were already played completely are freed from memory on every loadfile or loadmem command This is especially useful for online stimulus generation 40 where hundreds of new data segments are loaded during runtime starttimeout timeout in milliseconds that is allowed between command start and the start of the driver This is a debugging option for sound cards that respond very slow stoptimeout timeout in milliseconds that is allowed between command stop and real stop of the driver This is a debugging option for sound cards that do not really stop immediately after they are told to do so uginexe executable for plugin Leave this empty if running MATLAB or OCTAVE Only to be set if using compiled plugins see corresponding example uginstart MATLAB script to be executed on startup of MATLAB script plugin uginproc MATLAB script to be executed for each audio buffer within MATLAB plugin If this value is empty the MATLAB plugin interface stays disabled uginshow flag if MATLAB process created for MATLAB plugin should be shown 0 or 1 NOTE use only for debugging purposes NOTE for OCTAVE the workspace is only shown properly if pluginkill is set to 0 as well pluginkill flag if MATLAB process created for MATLAB plugin should be killed on exit 0 or 1 While SoundMexPro is initialized you cannot access the MATLAB window that runs the
8. So if you want to apply a multiplication on the final channel output be sure that you set the last track mapped to the corresponding channel to mode 1 track vector with tracks indices or cell array with names to apply mode to no duplicates allowed mode current modes no changes track vector with all tracks vector with current modes for all tracks start start starts input and output IMPORTANT NOTE record files are always overwritten Use the recfilename command to change the filenames if necessary NOTE recorded data are always stored in normalized 32 bit float PCM wave files NOTE if you get an error setting samplerate of device to XY not successful check if the sample rate is locked by the driver check control panel and or documentation of driver for more information IMPORTANT NOTE if you are running in file2file mode see command init then the command start will return after the file2file operation is complete Depending on your loadfile and loadmem calls this may take a while Afterwards the command cleardata is called automatically length running length Values for length may be lt 0 device is stopped playback and record after all tracks played their data NOTE After each ASIO buffer it is checked if no track has more buffered data to play If this is true the device is stopped device is never stopped zeros are played endlessly In this case you may load new data to track s at any time
9. VST plugins VST is a widespread audio plugin architecture worldwide and therefore thousands of plugins exist many of them are freeware Thus you can either benefit from the variety of existing VST plugins or develop your own plugins using the free VST DSK available from Steinberg http www steinberg com This chapter describes how to use VST plugins in SoundMexPro SoundMexPro is shipped with a growing number of VST plugins that require the VST license These plugins are described in the separate manual HtVst Plugins pdf At the moment all plugins can be loaded with the VST license as well but this may change at any time without notification Realtime processing with VST plugins is available only with the VST and VST license of SoundMexPro 7 2 1 l O configuration of VST plugins In general a VST plugin is a signal processing unit with a variable number of inputs and outputs A plugin reads data from the inputs applies its processing scheme on the data and writes the processed data to the outputs For the description of the I O configuration of VST plugins the so called routing it is very important to realize the difference between the plugins inputs and outputs and the SoundMexPro channels tracks or output channels respectively that are connected to those inputs and outputs of the plugin SoundMexPro supports three different types of VST plugins The type determines if a VST plugin is loaded as a master
10. language it is essential to take care of accurate error handling SoundMexPro provides a variety of commands tools to implement error handling for two types of errors that might occur 4 1 Synchronous errors in SoundMexPro Every SoundMexPro command returns an error code as first return value to MATLAB to indicate the success or failure of a particular command This may include simple syntax errors as well as failures accessing the soundcard Evaluating these return values carefully allows the user to detect problems immediately when they occur and avoid unpredictable script crashes if one SoundMexPro command on the way fails 4 2 Asynchronous errors in SoundMexPro Errors that do not occur as immediate result of a call to a SoundMexPro command are called asynchronous errors Such errors cannot be reported to MATLAB immediately i e at the time of their occurrence because there is no SoundMexPro command currently running that may accept any return value Therefore asynchronous errors are stored and the next SoundMexPro command will fail and show the corresponding error indicating it as an asynchronous error Such errors may occur during the runtime of SoundMexPro due to various reasons 4 2 1 Clipping The input or output of the device clips overdrive SoundMexPro detects and counts buffers where 1 0 clipping occurs The current value can be retrieved at any time with the command clipcount and the user may react o
11. Los restes ei eei ES Aorere 7 2 7 System Requireimeblts e eos ceto eria eo ne o or un eoo uo n uo o paseo ue en uve eu us Deos ev es oo es ep esee i es owe vod 7 2 2 Installing SoundMeXPr0 ieer ri tiet seco eee ine rte ae pee Else ce oae aee ER nga ee aa E 8 2 2 4 Accessing SoundMexPro help from MATLAB ccccececececececececececeeecececeeeeeceeeeeeeees 9 2 3 Uninstalling SoundMexPro eeeeeee esee esee eene eene nennen enne ener enne entree ener 9 3 TheSoundMexPro INterface cssseccccssscsscescecccccnacsessescecccecnacsescescncececnacsassescecccecnacasescnees 10 3 General Command Description eeececccccecececececececececececececececececececececesececeseseseceseeeeess 10 3 2 Architecture Output Channels and Virtual Tracks eene 12 3 3 Audio data in SoundMexPro files and vectors cccccccceeessssescececcceceeesencecececeeeeeseces 16 3 31 Loops ramps and crossfades eecececesecccececececececececececececececececececececeseceseeeeeeeeeeees 16 3 3 2 Channel align mMent cceccccccccccccccecececececececececececececececececececesecececeseseseceeeeeeeaeeenaes 18 3 4 B fferconfiguratiON ssis coerente one rero quen uocare eoque ee EE OE ue ar Ee Esei e EUN ea agnus 19 3 4 41 Sound card constraints minimum Celay ccccececececcecececececececececececececeseceseeeeeeeess 20 3 5 Supported audio file formats nennen enne esses sensns 20 4 ErrorHandlin
12. OPERE EE SER EUER OSETE a PEDET OPERETE ORE EDETS 62 ify SoundMexPro documentation 5 1 Introduction SoundMexPro is a powerful tool for sound applications in MATLAB and GNU Octave SoundMexPro is especially designed for acoustic measurement tasks Psychoacoustics Physical Acoustics Neuro Physiology ASiIO SoundMexPro uses the ASIO technology ASIO is a trademark and software of Steinberg Media Technologies GmbH v SoundMexPro uses the VST technology VST is a trademark and software of Steinberg Media Technologies GmbH SoundMexPro uses libsndfile 1 0 19 for reading sound files see also license section above See http www mega nerd com libsndfile for more information The software SoundMexPro is not a medical device or an accessory of a medical device respectively and not intended to drive a medical device The main features of SoundMexPro are Multichannel sound output and recording using the ASIO sound interface sample accurate synchronization of multiple playback and recording devices Reading multiple audio file formats Unlimited number of virtual audio tracks virtual recording mixing studio Real time mixdown of virtual tracks to output channels with separate level control for tracks and channels Record from multiple devices synchronously to disk hard disk recording Continuous sound adding mode new audio data can be added at any time while device is already playing e g for
13. a straight connection from track o to channel o track 1 to channel 1 and so on Determine the required wiring of tracks to output channels i e which track s are connected to which output channels and set this mapping using the trackmap command For simplicity reasons the example above describing the difference between tracks and output channels only used simple signal output without any DSP plugins and or signal input recording The complete processing scheme for each output channel i e how samples are generated and processed before they are sent to the sound card driver consists of the following steps see Figure 2 the numbers at the bottom correspond to the enumeration below soundcard recording channels soundcard output channels Recording Volume Harddisk Recording debugsave Channel 1 Master Master VST Script Plugin Plugin Master Volume Track Track Volume VST Plugins SoundMexPro documentation 14 1 Track data are retrieved from file or MATLAB vector 2 Data from input channels recording channels that are mapped to one or more tracks with command iostatus are added to the corresponding track s after the recording volume command recvolume and the recording VST plugins were applied Multiple input channels may be mapped to the same track dashed line or one input channel may be mapped to multiple tracks as well dotted line 3 Track
14. channel vector must be identical thresholds applied in corresponding order to specified channels channel vector with output channels indices or cell array with names to apply threshold to no duplicates allowed Def type output value current threshold values no changes channel vector with all allocated channels Ret vector with current thresholds for all input or output channels 04b 05a clipcount Name clipcount Help returns number of buffers not samples where clipping occurred NOTE for recording clipping is defined as two consecutive full Scale samples For the input channels clipping is checked before any gain and signal processing plugins is applied to detect clipping that occurred on D A conversion If you use any plugins that amplify the input such clipping is not detected by clipcount command Ret vector with number of buffers where clipping occurred for each allocated ouptut channel vector with number of buffers where clipping occurred for each allocated input channel vector with number of buffers where clipping occurred for each allocated track resetclipcount Name resetclipcount 04b Help resets all clip counters to zero SoundMexPro documentation 61 underrun underrun returns underrun status of all tracks 1 means that during playback the corresponding track ran out of data vector with zeros and ones denoting corresponding underrun status i e 1 if an underrun oc
15. column 1 gt track 1 column 0 track 4 column 1 gt track 7 or loading a mono matrix with an empty track argument will load that data to all tracks loopcount number of times the data are to be played NOTE 0 is an endless loop offset number of zero samples to be played in the beginning startoffset number of samples to be skipped from data when playing the first loop A value of 1 selects a random startoffset gain linear gain to be applied to each file sample crossfadelen length in samples for a crossfade done with the object vector or file that was loaded BEFORE this object If this object is set for the first vector in a track it is ignored ramplen number of samples for fade in and fade out hanning ramp of complete object i e the first ramplen samples of playback are ramped up and the last ramplen samples including all loops are ramped down NOTE ramplen must not exceed half of total play length ramplen loopcount length startoffset loopramplen number of samples for fade in and fade out hanning ramp looping of an object i e the first ramplen samples of each loop are ramped up and the last ramplen samples are ramped down NOTE the first samples of first loop are NOT ramped up and the last samples of last loop are NOT ramped down Use parameter ramplen additionally for an overall ramp loopcrossfade if this value is set to 1 then a crossfade with a length of loopramplen samples is done on loop
16. disabled e g MOTU soundcards Some soundcards keep the mappings between calls to allow mapping one input to multiple outputs Most RME soundcards support this behaviour at least the RME FireFace and the RME HDSP Series M je SoundMexPro documentation 36 8 1 2 Output gain pan control The RME FireFace and the RME HDSP Series support setting of output gain and pan instead of input gain pan To set gain pan for an output channel the mode of the adm command of SoundMexPro has to be set to the undocumented values 2 or 3 respectively In this case the value of input is ignored When setting mode to 2 pan is set but channel is muted gain set to o When setting mode to 3 pan and gain of the output channel are set to the requested values 8 1 3 ADM mixer feedback When using ADM commands RME FireFace and the RME HDSP Series the changes are reflected directly on the FireFace mixer or Hammerfall mixer respectively e g the slider positions will change When using MOTU soundcards the changes are done under the hood i e CueMix does not show the changed values 9 File to file operation with SoundMexPro SoundMexPro can be initialized in a so called file to file mode see command init In this mode no soundcard or driver respectively is used all data are processed as fast as possible and the output data that are usually passed to the soundcard dr
17. identical values applied in corresponding order to specified channels input vector with input channels indices or cell array with names to apply values no duplicates allowed Def value current mute values no changes track vector with all input channels Ret vector with current mute values for all input channels SoundMexPro documentation 55 recsolo Name gt recsolo none Help gt sets solo status of one or more input channels and returns current status NOTE muting unmuting is not ramped NOTE solo status supersedes mute status if solo status of any input is 1 then mute status of all inputs is ignored Par value vector with solo values 0 for unsolo or 1 for solo If no value is specified no solo values are changed current values are returned Either one value must be specified applied to all channels or lengths of solo and input vector must be identical values applied in corresponding order to specified channels input vector with input channels indices or cell array with names to apply values no duplicates allowed Def value current solo values no changes input vector with all input channels Ret vector with current solo values for all input channels recvolume recvolume sets recording volume and returns current recording volume of input channels value vector with volumes linear gains If no value is Specified no volume is changed current volumes are returned Either one volume mus
18. implementing timeouts vector with ones started and zeros not started for all allocated input channels reclength sets file record length and returns current values value vector with record lengths If no value is specified no value is changed current values are returned Either one value must be specified applied to all channels or lengths of value vector and channel vector must be identical record length applied in corresponding order to specified channels Recording to file on the corresponding channel is stopped after recording the specified number of samples 0 does endless recording NOTE this record length sets the length of the file to be reorded only If the recorded file exceeds this length only recording to file is deisabled the device itself is not stopped playback and recording to memory is still ongoing channel vector with channels indices or cell array with names to apply record lengths to no duplicates allowed value current record lengths no changes 0 on startup channel vector with all allocated channels vector with current file record lengths for all allocated channels SoundMexPro documentation 54 recbufsize Name gt recbufsize Help gt sets record buffer sizes and returns current values Par gt value vector with buffer sizes If no value is specified no value is changed current values are returned This value specifies how many recorded samples of a channel are b
19. it The RME FireFace for example supports modes 2 and 3 Using these values input is ignored and the gain and pan of output channel output are set instead of input channel input where mode 2 switches off muted i e gain 0 and mode 3 switches on i e gain gain is really set 0 0 536870912 hex 0x20000000 i e 0 dB 1073741823 hex Ox7fffffff 2 i e middle position 1 11 7 Error Handling This table contains commands related to error detecting and handling Please read the separate chapter on error handling carefully asyncerror Name asyncerror Help returns asynchroneous error status and error text Ret 1 if an asynchroneous error ocurred or 0 else error text if any resetasyncerror Name resetasyncerror Help resets asynchroneous error clipthreshold Name clipthreshold Help sets clipping threshold and returns current threshold values The clipping threshold is the normalized value between 0 and 1 that will be interpreted as clipping and thus will increase the clipcount if exceeded Default on startup is 1 for all channels real digital overdrive Par type input or output to set input recording threshold value s or output playback threshold value s value vector with thresholds between 0 and 1 If no value is specified no threshold is changed current thresholds are returned Either one threshold must be specified applied to all channels or lengths of threshold and
20. mexw32 mpluginmex mexw64 mpluginmex mex SMPIPC EXE SoundD11Pro dll soundmexpro old dll SoundD11ProLoader exe soundmexpro mexw32 soundmexpro mexw64 soundmexpro mex smp_stft m smp_stftinit m SMPPlugin m soundmexpro_showdevs m soundmexpro_showcfg m soundmexpro_trackmap m smp_disp m binNOctave 3 8 mpluginmex mex soundmexpro mex Fle Main program files and libraries license file Add this path to the search path of MATLAB or GNU Octave Tools used for spectral script based plugins Tool script to be used for compiling script plugins Tool scripts for examination of available hardware and configuration see tutorial t_o2b_config_tools m and commented scripts themselves Helper script used in tutorials and examples binaries needed for Octave 3 x Copy these files to the BIN directory if you are using Octave 3 x tutorial tutorial MATLABO script files examples various advanced MATLABG examples and examples using the VST plugins shipped with SoundMexPro manual SoundMexPro pdf PDF Help LGPL license information SoundDllProLoader pdf HtVst Plugins pdf lgpl txt manual html HTML help Copy HTML and subfolder LL Nes SoundMexPro documentation 8 related files SoundMexPro Files to your MATLAB ref path see below plugins VST plugins shipped with SoundMexPro waves various wave files used by the tutorial and the examples After installing you sh
21. mode output matrix with current plugin user data for all allocated channels SoundMexPro documentation 56 11 5 1 VST Commands This table contains commands related to VST plugins NOTE all these commands are only available with a VST license Command Description vstquery Name gt vstquery Help gt returns information on a VST plugin by filenname or by type input and position filename filename of plugin to query NOTE if filename is specified all other parameters are ignored type type of plugin to query Allowed types are master plugin loaded as master plugin track plugin loaded as track plugin input plugin loaded as input recording plugin input one of the plugins input channels specified when loading it with vstload position vertical position of plugin to unload type master position 0 effect name product string and vendor as returned from plugin number of available inputs number of available outputs cell array with available program names current program cell array with available parameter names vector with corresponding parameter values vstload vstload loads a VST plugin optionally with config file filename filename of plugin to load type type of plugin to load Allowed types are master plugin is loaded as master plugin it is plugged into hardware output channels i e applied on track sums after mixing track plugin is loaded as track plugin it is plugged int
22. not in the processing Both tasks are performed in different threads where the processing thread has the higher priority The command xrun returns the sum of both types for backwards compatibility the number of processing and the number of recording xruns separately pe SoundMexPro documentation 21 4 2 3 Data underrun A data underrun occurs in the output A data underrun occurs if the sound output is started command start and a channel has played all his data before receiving new data with loadfile or loadmem In most applications this underrun is not of interest usually the channels should run out of data after playing the desired samples but e g for continuous stimulus generation it might be necessary to detect underruns i e if you are too slow in generating new samples The command underrun retrieves the current underrun status for all channels Take e look at the tutorial script t o4c play con stim gen m 4 2 4 Setting changed If the sample rate or buffer size of the driver is changed externally e g from control panel of the driver during signal output the device is stopped and the error message for command asyncerror is set correspondingly 4 2 5 Fatal errors Fatal unexpected asynchronous errors during signal I O occurs Usually such errors should not occur if no hardware error occurs except if a plugin script plugin or VST plugin returns an error during signal processing Please
23. online stimulus generation Retrieve recorded data directly to MATLAB while device is recording e g for online evaluation Threshold driven recording DSP Plugins for real time signal processing o Script based plugins user defined MATLAB commands are called for every sound buffer on the fly Processed data are sent to the soundcard o VST Host for loading Steinberg Virtual Studio Technology VST effect plugins Direct low latency I O recorded data can be directly or after processing the data with DSP Plugins mapped to multiple tracks file to file processing Xrun dropout detection Special command for highlighting buttons on a MATLAB window buffer accurate highlighting at desired playback positions for signal synchronous user feedback Important note For understanding the basic concept of SoundMexPro it is very important to get familiar with and distinguish between Virtual Tracks and Device Channels Please read chapter 3 2 very carefully where these terms are introduced ig SoundMexPro documentation 6 A demo version of SoundMexPro is available for free The demo version has the following restrictions ademo message is shown on init and after every few minutes sound input and output is stopped every few minutes additional sound the spoken words SoundMex demo is added to all playbacks and recordings at random times 11 What s new in version 2 0 W
24. output is shown If the name is too long keep the mouse over the name to get a hint window with the full name The small red LED above the level meter indicates that clipping has occurred on the corresponding channel You can reset all LEDs by clicking one of them or with command resetclipcount You can change volume with the keyboard keys Up Down PageUp and PageDown With the TAB key you can walk through the sliders The slider that has the focus has a red line on its SoundMexPro documentation 25 thumb here track 1 Sliders which are currently not at position o dB have a green line on their thumb here track 2 You can toggle between o dB and last volume by a double click on the thumb or with the space bar I SoundMexPro Mixer Track 1 Track 2 Track 3 xruns 0 Figure 8 The SoundMexPro Mixer A track or channel can be muted unmuted by clicking button M or keyboard shortcut M A red button indicates that mute is active here output 1 A track or channel can be switched to solo by clicking button S or keyboard shortcut S A yellow button indicates that solo is active here tracks o and 1 NOTE Solo supersedes mute You can link a track or channel to his left neighbour by clicking the link button L or keyboard shortcut L If channels are linked volume solo or mute changes are applied to all linked tracks or channels respecti
25. plugin so this parameter may be useful to keep the window alive after quitting SoundMexPro to check variables in plugin s workspace NOTE use only for debugging purposes NOTE if pluginshow is set to 0 and pluginkill to 0 then you only can kill the processing MATLAB OCTAVE instance with the task manager plugintimeout timout in milliseconds for startup of the plugin Set this value to higher values if your startup script for the plugin takes some time pluginforcejvm flag if the MATLAB instance running the plugin should be started with Java Virtual Machine JVM It is highly recommended NOT to use this flag since the JVM lowers the performance of plugins significantly Additionally you may have to increase the value of the parameter plugintimeout because the MATLAB startup might be very Slow This parameter is ignored for Octave name of a file for command and return value logging If it is set non empty all commands and return values are written to this file not in MATLAB but SoundDllMaster syntax NOTE if write access to file fails read only of invalid filename init command will fail vstmultithreading flag if each parallel VST plugin should run in a Separate thread vstthreadpriority thread priority for VST threads Must be between 0 and 3 0 normal 1 higher 2 highest 3 time critical Setting value to 3 time critical will give highest priority to processing but may block other processes This value is ignored
26. running example and an example where processing is too slow as well More fully functional examples are located in the examples subdirectory SoundMexPro is shipped with additional helper scripts for manipulations in the frequency domain They implement a block by block overlapped add FFT filter with zero padding stft in the two helper scripts smp stftinit m and smp_stft m located in the BIN subdirectory The usage is demonstrated in the tutorial scriptt 07b realtime plugin spec m and some helper scripts pe SoundMexPro documentation 29 Realtime processing with MATLAB scripts is available only with the DSP and DSP VST versions of SoundMexPro 7 1 1 Using compiled script plugins If you want to use signal processing with MATLAB scripts that were compiled with MATLAB into executables you have to do some adjustments and compile the plugins separately An example with detailed descriptions can be found in the examples subdirectory of the installation Instructions and detailed descriptions how to compile and debug such applications are contained in the scripts MainScript m and mainly in SMPPlugin m in the BIN directory of the SoundMexPro installation The script SMPPlugin m ist intended to be used for all you compiled script plugins only the compiling command line has to be adjusted see comments in file 7 2 Realtime processing with VST plugins SoundMexPro supports loading of Steinberg Virtual Studio Technology
27. vector with corresponding parameter values vststore Name vststore Help stores current configuration of a VST plugin in a config file description of format see manual Par type type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried input one of the plugins input channels specified when loading it with vstload position vertical position of plugin to query configfile filename of config file to write to NOTE and existing file will be overwritten Def type master position 0 vstedit Name vstedit Help shows a GUI parameter editor of a VST plugin Par type type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried input one of the plugins input channels specified when loading it with vstload position vertical position of plugin to query Def type master position 0 SoundMexPro documentation 59 11 6 Other Commands This table contains commands related to direct I O and other special commands Command iostatus setbutton dspload dsploadreset adm Name gt iostatus Help gt sets I O status of an input channel and returns current status Par gt input vector with input channels indices or cell array with names to map This value is mandatory If one channel is specified then this input is mapped to all
28. vector with number of samples recorded on each allocated input channel NOTE all allocated channels do always record data from the soundcard so the absolute recording position is determined by position This command returns how many samples are saved to disk for each channel During recording saving might be enabled and disabled multiple times recposition returns the total number of saved samples recthreshold sets record threshold and returns current value value Thresholds between 0 and 1 current value is returned If no value is specified the current value is not changed A value of 0 disables the threshold Otherwise recording to file starts with the first recorded buffer not sample that contains data that exceed the threshold value with respect to the specified mode and channels NOTE threshold is resetted after exceeding it set to 0 Flag if the threshold must be exceeded in one 1 or all 0 of the channels specified in channel Must be 0 or 1 channel vector with channels indices or cell array with names to check for the threshold no duplicates allowed value current thresholds no changes 0 on startup mode 1 channel vector with all allocated channels current threshold value current threshold mode recstarted returns if recording to file channels was ever started This command is especially useful when recording with threshold to check if the threshold value was ever exceeded e g for
29. volumes are applied The completely calculated track data are passed to the track VST plugins for processing NOTE depending on your VST plugin configuration data across tracks may be mixed see chapter 7 2 5 Generate output data from track data iteration through all virtual tracks containing the data processed so far with ascending indices The track data are applied to their output channel where applied means a they are added to the output default b the current output is multiplied sample by sample with the data if the track is in multiplying mode see command trackmode In this case the order of the tracks is important if you have e g initialized 4 tracks for an output channel and have set the third track to multiplying mode then the sum of the first two tracks is multiplied with the third track and the fourth track is added to the result of that operation 6 The completely calculated output channel data are passed to the master VST plugins of the output channel for processing NOTE depending on your VST plugin configuration data across output channels may be mixed see chapter 7 2 7 The completely calculated input and output channels are passed to the MATLAB script DSP interface of SoundMexPro Important note the input channels passed to the MATLAB script DSP interface are the recorded data received from the driver and processed by the optional recording VST plugins dash dotted line
30. with the main menu View gt Display Format The current cursor position is shown at the left bottom of the screen left of the horizontal scrollbar You can zoom vertically and horizontally with the and a buttons next to the corresponding scrollbars a zooms out to show all tracks or samples respectively The tracks are arranged horizontally The dark blue box to the left of each track shows track number device output channel where the track is connected to and a list of input channels that are mixed added to this track if any mi sounaMexPro Tracks o ceo jS a am View About 00 00 08 640 00 00 10 st 000008034 lt WIRT device stopped xruns 0 DSP 0 2 M Data that were loaded to a track are shown as green files and blue vectors boxes Please note that names of vectors can only be shown if the optional argument name is specified in command loadmem Vertical dotted lines indicate loops of a file vector e g the vector sweep in the figure is played three times Vertical dotted lines connected with a cross indicate a crossfade e g eurovision wav loaded to Track 3 During playback a vertical cursor shows the current playback position You can set the current position by clicking with the right mouse button at the desired position while holding the Ctrl Key pressed The status bar contains information about the device status n
31. MATLAB process to find it pluginproc Name of a MATLAB script to be called for each data audio block The called script must implement a function taking four input arguments and returning four matrices of same size e g function proc_indata proc_outdata proc_inuserdata proc_outuserdata plugin proc script indata outdata inuserdata outuserdata The passed arguments are indata Matrix with inchannels columns and samples rows containing the currently recorded samples as passed in pluginstart outdata Matrix with outchannels columns and samples rows containing the current samples to be passed to the driver next inuserdata Matrix with inchannels columns and 100 rows containing user data for interprocess communication between main MATLAB GO and processing MATLAB instance see below outuserdata Matrix with outchannels columns and 100 rows containing user data for inter process communication between main MATLAB and processing MATLAB instance see below The function must return four matrices of identical size ee SoundMexPro documentation 28 NOTE take care that the resulting samples after processing are between 1 and 1 otherwise clipping will occur except if channel volume was set with command volume this volume is applied after calling the plugin NOTE take care that your processing is not too slow i e consumes more time than s
32. MexPro containing a mixdown of multiple tracks can be connected to one channel of the sound card called device channel below The figure below shows an example using three output channels connected to three corresponding device channels and six virtual tracks are used virtual playback cursor Track Master jo Volume Volume Sound card ee Im 0 P De xq o file 7 p The command sequence for setting up SoundMexPro for the configuration shown above is described here in detail in anticipation of the command list below most arguments omitted to use default values initialize SoundMexPro with three output channels and six track soundmexpro init X ete 5 command name gyucput 0 9 Gl sas use three output channels connected to device channels 0 5 and 6 of the sound card xe G T use 6 tracks LL Nue SoundMexPro documentation 12 Note after initialization the three allocated output channels are enumerated in SoundMexPro starting with o i e first sound card device channel o will have output channel index o in SoundMexPro sixth sound card device channel will have output channel index 1 and seventh sound card device channel will have output channel index 2 The default track mapping wiring of tracks to output channels after command init if track parameter is omitted is one track per output channel where the first track is connected to the fi
33. NOTE if you record data to a file this runs forever as well and files may become quite huge length in samples to play record before device is stopped NOTE this length will not be sample accurate due to block processing This parameter is ignored in file2file mode if set to 1 device is paused rather than stopped This parameter is ignored in file2file mode 1 If NO output channels are specified on init for output then default is 0 0 startthreshold startthreshold Starts input and output after threshold value is exceeded in one or more input channels IMPORTANT NOTE the command returns immediately to MATLAB real start of input and output waits for the threshold to be exceeced If you want to check if threshold was exceeded meanwhile after calling startthreshold use the command started while waiting for threshold it will return 0 in second return value afterwards it will return 1 This way you implement a waiting loop with timeout After the threshold is exceeded the playback starts immediately but it will start with numbufs ASIO buffersize zero samples see parameter numbufs of command init IMPORTANT NOTE record files are always overwritten Use the SoundMexPro documentation 45 started stop pause mute trackmute recfilename command to change the filenames if necessary NOTE recorded data are always stored in normalized 32 bit float PCM wave files NOTE if you get an error s
34. SoundMexPro for sound applications in MATLAB and GNU Octave Version 2 2 0 3 ASIO Sound Toolkit for MATLAB and GNU Octave http www soundmexpro de User Manual HorTech Research amp Development Copyright H rTech gGmbH Marie Curie Str 2 D 26129 Oldenburg Germany http www hoertech de No warranty subject to alteration SoundMexPro documentation Software Version 2 2 0 3 October 6 2015 License agreement IMPORTANT PLEASE READ CAREFULLY BY INSTALLING THE SOFTWARE AS DEFINED BELOW COPYING THE SOFTWARE AND OR CLICKING ON THE ACCEPT BUTTON BELOW YOU EITHER ON BEHALF OF YOURSELF AS AN INDIVIDUAL OR ON BEHALF OF AN ENTITY AS ITS AUTHORIZED REPRESENTATIVE AGREE TO ALL OF THE TERMS OF THIS END USER LICENSE AGREEMENT AGREEMENT REGARDING YOUR USE OF THE SOFTWARE IF YOU DO NOT AGREE WITH ALL OF THE TERMS OF THIS AGREEMENT DO NOT INSTALL AND OR USE THE SOFTWARE DEFINITIONS The term Software includes all software distributed with this License including all documentation The Software is licensed to you under the terms specified in the License Grant below HIGH RISK ACTIVITIES The Software is not fault tolerant and is not designed manufactured or intended for use as on line control equipment in hazardous environments requiring fail safe performance such as in the operation of nuclear facilities aircraft navigation or communication systems air traffic control direct life support machines or othe
35. Within the interface you can mix add copy data between the inputs and outputs This means that there are two ways of mixing inputs to the outputs either using command iostatus see step 2 above or within the MATLAB script DSP interface of SoundMexPro 8 Finally the channel volume see command volume is applied NOTE after all these calculations the data are passed to the driver If the data contain values above 1 or below 1 clipping will occur So you have to take care especially when using multiple tracks that the sum of your data does not exceed these limits The light blue boxes labelled Harddisk Recording and debugsave show how data are saved to disk in SoundMexPro Recording data command recfilename are written WITHOUT applying signal processing except for recvolume Data saved with command debugsave store the completely processed data of an output channel It is always recommended to record unprocessed data to disk and apply any signal processing later In this way you can always fall back to the original data later again otherwise you only will have the processed data available However if you want to record processed audio data directly to disk you may use the following procedure disable recording to file command recpause use command isostatus to map inputs to tracks plug your plugin into the recording channel or track or output pe SoundMexPro documentation 15
36. ails as a result of accident abuse misapplication or modification LIMITATION OF LIABILITY You must assume the entire risk of using the Software IN NO EVENT SHALL H rTech gGmbH BE LIABLE TO YOU FOR ANY DAMAGES INCLUDING ANY LOST PROFITS LOST SAVINGS OR OTHER INCIDENTAL INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING OUT OF THE USE OF THE H rTech gGmbH s SOFTWARE EVEN IF H rTech gGmbH HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES IN NO EVENT WILL H rTech gGmbH s LIABILITY FOR ANY CLAIM WHETHER IN CONTRACT TORT OR ANY OTHER THEORY OF LIABILITY EXCEED THE LICENSE FEE PAID BY YOU THIS LIMITATION SHALL APPLY TO CLAIMS OF PERSONAL INJURY TO THE EXTENT PERMITTED BY LAW LIBSNDFILE LICENSE SoundMexPro uses the libsndfile library written by Erik de Castro Lopo and others http www mega nerd com libsndfile It is published under the GNU Lesser General Public License LGPL either version 2 1 or optionally version 3 see files libsndfile lgpl v2 1 txt and libsndfile Igpl v3 txt shipped with SoundMexPro pe SoundMexPro documentation 3 Contents License ASTECOMENL ccsnsccssecdssoacconSsenaucvesegsucadoeneucyesescnedbenseevssesensosbevencsesossteutbensuevesbdeuvnbbestsssssecesses 2 A MAEPOAUCEION ERR 6 11 What s new in version 2 0 cscccececcccceesssescececcceceeessescececececeeuseccececeeeeuaeaseecececeeeeeeeenes 7 2 fstallatio n icaiieen cssdesecbiccduel Ee eeei ee exeat Et esee Tei u eto Pese eec ea vea
37. amples samplerate otherwise xruns dropouts will occur Use the command xrun to detect dropouts Important note this script must be in the search path of MATLAB to enable the separate processing MATLAB process to find it pluginshow Debugging flag If set to 1 the separate processing MATLAB instance window is shown This is useful to debug your startup or processing script because all errors occur in those scripts will be shown in that workspace If set to o default the window stays invisible Note during the runtime of SoundMexPro the processing MATLAB instance window is blocked you cannot access it move it scroll it you have to call exit to unblock it Use only for debugging purposes pluginkill Debugging flag If set to o the separate processing MATLAB instance is not terminated on exit of SoundMexPro This is useful for accessing the window to check errors see also pluginshow If set to 1 default the processing MATLAB instance is terminated on exit Use only for debugging purposes Note if pluginkill and pluginshow set to o the process will run invisible forever You can only kill it with the task manager plugintimeout A timeout in milliseconds for startup of the plugin This includes startup of the processing MATLAB instance and processing of the startup script specified in pluginstart Default value is 10000 10s Must be increased if startup script is
38. and so on If more tracks than channels are specified circular means that mapping starts at channel 0 again E g specifying 0 1 2 in output and 8 tracks leads to the following mapping track0 gt channelO trackl channel track2 channel track3 channel track5 channel c fe track4 channel fe c track6 channel track7 channel The current mapping can be retrieved with the command trackmap On startup all tracks are in standard mode 0 adding i e data samples are added up on the corresponding output channel The mode of tracks can be changed with command trackmode ramp length in samples applied when starting stopping muting unmuting pausing unpausing and setting master volumes command volume number of buffers each size of current ASIO buffer size used for software buffering Increases I O delay and delay for commands like volume or pause to be applied but lowers risk of xruns to occur NOTE read the special section Buffer configuration in manual if you need low latencies NOTE ignored for file2file operation flag if audio data vectors or files that are already played completely should be cleared from memory auto matically on next data loading command Set this to 0 if you want to use the playposition command to rewind to a certain playback position with parameter position audio data segements are kept loaded until stop command
39. annel is currently recording data or 0 if not NOTE all allocated channels do always record data from the soundcard but recording determines if the data are currently saved to disk recfilename recfilename sets one or more record filenames for one or more channels and returns current name s NOTE value can only be set if device is stopped NOTE you cannot use the same filename for different channels only one mono file per channel can be written If an invalid filename is passed or a filename that is already used by another channel you may get errors on start You can set change the filename of a channel either if device is stopped or if the corresponding input channel s are paused with command recpause If you set a record filename for a paused input channel the current record file filename before setting the new one is closed and the new one created If a record length was set with command reclength the new file again will only record the specified number of samples NOTE record files are always overwritten i e if the same name is specified again in pause mode the file is overwritten directly NOTE recorded data are always stored in normalized 32 bit float PCM wave files NOTE never store record files directly on network drives or other Slow drives This may cause dropouts xruns To disable recording to file for one or more channels use the command recpause filename cell array with one or more filename
40. annot mix or process recorded data before they are passed to the outputs in ADM mode The SoundMexPro command adm interfaces directly to ASIO ADM Please check the help for the command for details Originally ADM was intended to map multiple inputs to a pair of channels stereo Gain and pan where intended to be applied to the input channels only However some hardware manufacturers have extended the functionality to set output gain pan as well or to map single inputs to multiple outputs These features are not part of the ADM specification and therefore they may not work with every soundcard NOTE The parameters to be used with the adm command of SoundMexPro are identical to the original ASIO parameters of the ASIO SDK from Steinberg where mode corresponds to the state flag in the SDK Thus you have full and direct access to the API of ADM However as stated above which undocumented parameters are supported by a particular soundcard or which features are supported at all are part of the soundcard drivers and cannot be changed or extended by SoundMexPro 8 1 Extensions hints for particular sound cards 8 1 1 Mapping inputs to multiple outputs Most soundcard drivers are using ADM switches as radio buttons i e if an input channel is mapped to monitored by a particular output channel and in a subsequent call the same input is mapped to another output channel then the mapping to the first channel is
41. aster volume i e it is applied after all signal processing and mixing as a linear factor to each sample channel vector with output channels indices or cell array with names to apply volume to no duplicates allowed Def value current volumes no changes channel vector with all allocated channels Ret vector with current volumes for all allocated channels SoundMexPro documentation 51 trackvolume Name gt trackvolume Help gt sets volume and returns current volume of tracks Par gt value vector with volumes linear gains If no value is specified no volume is changed current volumes are returned Either one volume must be specified applied to all tracks or lengths of volume and track vector must be identical gains applied in corresponding order to specified tracks track vector with tracks indices or cell array with names to apply volume no duplicates allowed ramplen ramplength in samples to use for fading from current volume to new volume Def gt value current track volumes no changes track vector with all tracks ramplen 0 Ret vector with current volumes for all tracks debugsave debugsave sets debugsave mode and returns current mode value vector with ones and zeroes If no value is specified no mode is changed current modes are returned Either one mode must be specified applied to all channels or lengths of mode vector and channel vector must be identical modes applied in corresp
42. be identical to number of channels or must be empty No duplicate names allowed If empty only current names are returned input vector with all input channels name empty vector cell array with symbolic names of input channels exit exit de initializes SoundMexPro 11 2 Device Commands This table contains commands related to ASIO devices e g query for existing drivers and channels Description Tut getdrivers getdrivers 02 returns names of all installed ASIO drivers vector with ASIO driver names getdriverstatus getdriverstatus 02 returns status of all installed ASIO drivers vector with ASIO driver status 1 ok 0 error getchannels getchannels 02 returns names of all channels of an ASIO driver NOTE if SoundMexPro is already initialized the parameters are ignored and the current driver is queried driver name or index of ASIO driver to query SoundMexPro documentation 43 Command Ret getactivedriver getactivechannels getproperties controlpanel Par Def 11 3 Playback Commands This table contains commands related to audio output vector with names of ouptut channels vector with names of input channels getactivedriver returns the name of the active ASIO driver name of the ASIO driver used in command init getactivechannels returns the names of all channels of current driver that were allocated in init vector with names of allocated o
43. curred on the track or 0 if not xrun xrun returns number of xruns occurred since last start total number of xruns occurred since last start number of processing xruns occurred since last start number of xruns in visualization and recording to disk since last start showerror showerror sets error printing behavior of SoundMexPro and returns current value mode 1 all errors are printed to MATLAB workspace 0 no errors are printed to MATLAB workspace current value getlasterror getlasterror returns last error last error as string 12 FAQ Please refer to the file FAQ TXT in the installation directory of SoundMexPro or to the SoundMexPro homepage http www soundmexpro de 13 Version History Please refer to the file HISTORY TXT in the installation directory of SoundMexPro or to the SoundMexPro homepage http www soundmexpro de SoundMexPro documentation 62
44. e where two audio objects where loaded the second with a crossfadelen of x samples For better illustration of the overlap the two objects are shown stacked the final output is the sum of both object 1 object 2 NOTE the total playback length will be shorter than the sum of the total lengths of the two objects by x Parameter loopcrossfade Crossfades between loops within an audio object If loopcrossfade is set to 1 then the value of parameter loopramplen is used for this object internal crossfade In the example shown below an object was loaded with a loopcount of 3 a loopramplen of x samples and loopcrossfade 1 For better illustration of the overlap the three loops are shown stacked the final output is the sum of all three NOTE the total playback length will be shorter than loopcount objectlength by loopcount 1 x thao SoundMexPro documentation 17 3 3 2 Channel alignment When using multichannel audio objects to SoundMexPro they are loaded with keeping their channels aligned This means that the channels are not shifted against each other even if the tracks where the channels are loaded to already contain data with different lengths This is illustrated with an example in Figure 6 virtual playback cursor The tracks o and 1 already contained data of different length green boxes when loading the stereo file 4 blue boxes with the command soundme
45. er hides mixer channelname channelname sets symbolic name of one or more output channels and returns current names These names can be used in all commands using outputs instead of their indices output vector with output channels indices or cell array with names no duplicates allowed vector cell array with names to be set Number of names must be identical to number of channels or must be empty No duplicate names allowed If empty only current names are returned output vector with all output channels name empty vector cell array with symbolic names of output channels trackname trackname sets symbolic name of one or more output tracks and returns current names These names can be used in all commands using tracks instead of their indices track vector with output tracks indices or cell array names no duplicates allowed vector cell array with names to be set Number of names must be identical to number of tracks or must be empty No duplicate names allowed If empty only current names are returned track vector with all tracks name empty vector cell array with symbolic names of output tracks recname recname sets symbolic name of one or more input channels and returns current names These names can be used in all commands using inputs instead of their indices input vector with input channels indices or cell array with names no duplicates allowed vector cell array with names to be set Number of names must
46. eration with SoundMexPro ceeeeeeeeee eene 37 10 SolrdMexPro VELSIONS iet ie terrier Ee arabo eda Der toi exa rre FEE PEE One EEEN Ra EESSI 37 10 1 SOUMGMEX PIO mesi EET See tentis ee EO beu EEE eee P eR ERR E SEUER CENTRES bea E aegra 37 10 2 SoundMexPro DSP iiiiieie eser era eina Ee eror er eara o er eee e Ee ieu pe roue elena ree pevee ree nera rede eu 38 10 3 SoundMeXxPro VS Teese aiceesor SEU rint eesete uec Ge Er erso PE eee poe eon Ute Ma eade ise rece Meo Ede Hover od 38 10 4 SoundMexPro pc 38 11 SoundMexPro Command Reference ccccececececececeececeeececeeeceeeeeceseceeeeeseeeseeeseceeeeeseeeeeeees 39 11 1 General COMMANAS RR 39 11 2 Device Commands icr reor eee ero tu ien vh eu eu eT CERE eR e e e EXE seen ete EE SEERE EESE 43 11 3 Playback Command S siue e reris eere nro err ER ere EIER KEKEN EDESA EEEE 44 11 4 Recordings Comialids eroe eoo ae eene ae eoo ee eee aee rete ro eee eene Ee eoa rra ee aae edge E reped 53 11 5 MATLAB script DSP commands eeeeeeee esee eene ener ener eere eene eene enean 56 11 5 1 VST COMMAMNAS eee eee eoe eoe eoo tno eene siS steel eo e ess vo ee esee s Vasa tes E EEES E 57 11 6 erigere M 60 11 7 Error Hatidllng eene erae Gee rore heo orate lovee exceeds duu Dae eE eode ade nee ve reed eius 61 12 C 62 13 Version HISEDIV esso eoo osea eR co a eR eR Y PERR Ee FREE ER E ERES ER CCS
47. es no changes output vector with all output channels Ret vector with current solo values for all output channels loadmem Name loadmem Help loads audio data to one or more channels see also chapter o NOTE while the device is running you may load more data to any track at every time However if you load too many data segments file or mem you may produce heavy memory load that may result in dropouts or even crashes Use the command trackload to check how many data segments SoundMexPro documentation 47 are currently pre loaded to the tracks and adjust the speed of loading new data on the fly if necessary On loading new data segments all data that are played not in use any more are removed automatically Par gt data matrix with one or more columns of data mandatory IMPORTANT NOTE matrices with more than one channel are loaded aligned to the specified tracks to keep the columns synchronous for playback i e there may be zeros prepended to one or more columns if necessary track vector with tracks indices or cell array with names were data to be played no duplicates allowed The number of tracks must be a multiple of the number of data channels columns of data If tracks devided by channels is 1 the data are loaded circular to the specified tracks e g loading a data matrix with two columns and specifying 01 4 7 in track then the data columns are loaded as follows column 0 gt track 0
48. etting samplerate of device to XY not successful check if the sample rate is locked by the driver check control panel and or documentation of driver for more information NOTE this command is not available in file2file mode Par gt value Threshold between 0 and 1 current value is returned If no value is specified the current value is not changed A value of 0 disables the threshold Otherwise playback and recording starts with the next buffer after the threshold was exceeded with respect to the specified value mode and channels NOTE threshold is resetted after exceeding it set to 0 Flag if the threshold must be exceeded in one 1 or all 0 of the channels specified in channel Must be 0 or 1 channel vector with input channels indices or cell array with names to check for the threshold no duplicates allowed length running length Values for length may be lt 0 device is stopped playback and record after all tracks played their data NOTE After each ASIO buffer it is checked if no track has more buffered data to play If this is true the device is stopped device is never stopped zeros are played endlessly In this case you may load new data to track s at any time NOTE if you record data to a file this runs forever as well and files may become quite huge length in samples to play record before device is stopped NOTE this length will not be sample accurate due to block processing This paramete
49. eturn value is an error code and indicates success or failure of the command itself where 1 is returned on success and o on any error Evaluate this first return value to react on any error before calling further SoundMexPro commands e g success soundmexpro init if success error Cannot initialize SoundMexPro end Commands with additional return values write these to outarg 1 outarg n e g success lasterror soundmexpro getlasterror pe SoundMexPro documentation 10 if success 1 error error calling getlasterror end disp the last error was lasterror Important notes Jf any error occurs within a command the additional output arguments may contain only a scalar value zero and must not be used In this case only the error code is valid All string values are returned as cell arrays The standard error code return argument is omitted in the list of outargs in the help command and in the command tables below All commands return the error code as first outarg The next paragraph contains a description of the internal SoundMexPro architecture using output channels and virtual tracks Read this carefully because it is very important to get the idea of this concept to be able to tap the full potential of SoundMexPro SoundMexPro is shipped with a tutorial and some advanced examples It is highly recommended to examine the tutoria
50. file This applies for all played loops i e the first fileoffset samples of the file are never played length sets the total length in samples to be used for each loop see also description below The range of the file to be used is generated from these parameters and the file is looped if necessary i e if fileoffset length gt filesize in samples You can set the start playback sample for the first loop within this range with the parameter startoffset Must be between 1 random and length fileoffset number of samples to skip in the beginning An offset of 1 starts at a random position within the file NOTE this applies for all loops first fileoffset samples of the file will never be used see description of startoffset length in samples to play per loop Must be between 0 and length of the used range of the file in samples see also description of startoffset 0 uses all samples starting at fileoffset to the end of the file gain linear gain to be applied to each file sample crossfadelen length in samples for a crossfade done with the object vector or file that was loaded BEFORE this object If this object is set for the first vector in a track it is SoundMexPro documentation 49 ignored number of samples for fade in and fade out hanning ramp of complete object i e the first ramplen samples of playback are ramped up and the last ramplen samples including all loops are ra
51. from track plugins input plugin is unloaded from input plugins one of the plugins input channels specified when loading it with vstload NOTE plugin is unloaded completely it s removed from all channels where it was loaded to vertical position of plugin to unload master 0 sets and retrieves a program of a VST plugin type input position program type position type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried one of the plugins input channels specified when loading it with vstload vertical position of plugin to query name of program to select If empty value is not changed master 0 current program name vstprogramname sets and retrieves the name of the current program of a VST plugin NOTE this command does not select a new program by name it renames the current program NOTE the plugin itself has to support this renaming otherwise the command will fail type input position type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried one of the plugins input channels specified when loading it with vstload vertical position of plugin to query programname new name to set for current program If empty value SoundMexPro documentation is not changed Def gt t
52. g different sine signals loaded to the different tracks SoundMexPro can load multiple VST plugins for subsequent processing Up to five plugins can be loaded to each channel the argument position specifies the so called vertical position layer of a plugin denoting its position within this subsequent processing chain The audio data are passed first to the plugin at position o the output of plugin o is passed to plugin at position 1 and so on as demonstrated in Figure 12 For simplicity reason the figure shows only two SoundMexPro channels and VST plugins with one channel each using straight routing i e inputs and outpus of the plugins are always identical For a more sophisticated example please take a look at the tutorial file t oob vst artificial m that uses multiple plugins in multiple vertical layers with cross routing from to different tracks applying simple gains to some artificial data for illustrating the usage of routing with plugins pe SoundMexPro documentation 32 SoundMexPro channel o SoundMexPro channel 1 Position o Position 1 Position 2 Position 3 Position 4 Figure 12 Vertical positions of VST plugins in SoundMexPro Additionally a VST plugin can be configured to use a copy of data from a different channel and position within this data flow as it s input rather than the subsequent audio data within a channel This may be used for a recursion e g to implement adaptive filte
53. g in SOUMAMEXPLO cccccccececececececececececececeeecececeecececececesecececesecececeseceseceseseses 21 4 1 Synchronous errors in SoundMexPro eeeeseeeeee esee eese eene enean nennen 21 4 2 Asynchronous errors in SoundMexPro cesses eese eene eene eene ennt ener 21 P VANEEESIIOHCEEE 21 E MED LEE 21 42 3 Data Urnderruriziideesee eoe eteo estet e ege eo e evo ee dese eye eae a eee aU ee Reset e e Eee NYSE EN oTe e ree des 22 42 4 Setting changed iie tiit oreet Pea e en CES areeiro eva Eee ute ire Rae uev dads 22 AQ EE CIE CREE 22 5 Tutorial Examples and ScC nari0S ccccsessseseseseseseseseseseseeeseseseseseseseseseseeeseseseeeeseeeseeeees 22 541 IheSoundMexPro Tutoriales unie rto rere etre i eo nean E e YE Fe Vea e doe e YR ge ga 22 5 2 The SoundMexPro ExXaMPles ccccscsesssssesseeseseseseseseseseseseseseseseseseseseseseseseseseseseseeeeees 24 5 3 Using SoundMexPro without MATLAB cccccscssssssseseseseseseseeeseseseeeeeseseseseeeseseeeeees 25 5 3 1 Using the SoundDIlProLoader cececesececeeececcecececececececeeeceeececeeececeeeceeeseeeeeseceees 25 53 2 Programming Interface API cssvsissiventiainisnnnisiesstosionsuonnsysvevannbinnersyaunsenininnnroiiicinaits 25 6 SoundMexPro GUI interfaces cscccccccccccessssecececccecescsseccececececuecsseceecececeeeacaeseececsceeeaeans 25 63 IheSo ndMexPro MIXET iieri eret Exe erat e
54. hdoc ref e g C MATLAB6p5 help techdoc ref 2 3 Uninstalling SoundMexPro An uninstaller is shipped with SoundMexPro Run the uninstaller from the control panel pe SoundMexPro documentation 9 3 The SoundMexPro Interface This chapter describes the general command interface and architecture of SoundMexPro All SoundMexPro commands are listed and described in the command reference in chapter 11 3 1 General Command Description All SoundMexPro commands have a similar syntax errocode outargl soundmexpro command parl vall par2 val2 All command arguments except for command help have to be specified in pairs of parameter name and value e g soundmexpro loadfile command name filename noise 16bit wav name of wavefile semel 9 ij Vilocoacoume 4 5 5 tracks where to play file oo oe oe play it 1 time Most of the parameters have default values and thus can be omitted some are mandatory see help on commands below Note all indices in SoundMexPro are zero based i e the first output track or input respectively has index o second has index 1 and so on However you can assign symbolic names to all outputs tracks and inputs using the commands channelname trackname and recname Afterwards you can use these names in all commands optionally instead of their indices All commands return one output argument at least This r
55. hout argument a command list is printed in alpha betical order Name gt about Help gt Shows an about box with information about SoundMexPro Name gt setdrivermodel Help gt sets driver model Command init must not called before Driver model wdm is only available for Windows Vista or later NOTE it is STRONGLY recommended NOT to use the wdm mode Try to use tools like ASIO4A11 or Jack instead NOTE in wdm mode only 2 output channels and no inputs are supported xrun and controlpanel are not supported with wdm NOTE calling exit clears the driver model thus you have to call setdrivermodel again after calling exit Par value asio or wdm Def value asio Name getdrivermodel Help returns current driver model Ret current driver model Name init 01 Help initializes module 07 Par force if set to 1 exit is called internally before IL driver name or index of ASIO driver to use NOTE ignored for file2file operation file2file if set to 1 all final output channel data are written to files no soundcard used at all For default output file see command debugsave To change filename see command f2fnames to set buffersuze to be used see f2fbufsize f2fbufsize buffersize to be used for file2file operation samplerate samplerate to use NOTE after intialization only this SoundMexPro documentation 39 autocleardata SoundMexPro documentation sam
56. hus the data that will be received on this plugin s input will be the last block i e the SoundMexPro documentation 57 Def gt Ret vstunload vstprogram vstprogramname recursepos program data are prom the past one ASIO buffersize from the past NOTE the number of values must be identical to the number of 1 values passed to input vector specifying one or more positions for recurse input configuration see recursechannel If a value of 1 is specified this plugin s position is used i e a direct recursion from the output of the plugin to one of it s inputs NOTE the number of values must be identical to the number of 1 values passed to input program name to set programname new name to set for current program This name is set configfile type output position after program was selected optional filename of config file to use description of format see manual NOTE other parameters passed to command supersede corresponding entries in config file master input 0 recursechannel empty vector recursepos empty vector type of plugin master or track row vector with input channels row vector with output channels vertical vstunload position unloads VST plugin type position type position vstprogram type of plugin to unload Allowed types are master plugin is unloaded from master plugins track plugin is unloaded
57. if vstmultithreading is 0 quiet if set to 1 then no version info is printed to workspace Def force empty driver 0 file2file 0 fZfbufsize 1024 samplerate 44100 output 0 1 first two channels for regular operation 2 for file2file operation input 1 no recording at all track one track for each allocated output channel ramplen samplerate 100 numbufs 10 for ASIO driver model 20 for WDM autocleardata 0 starttimeout 6000 SoundMexPro documentation 41 initialized version show hide showtracks hidetracks updatetracks showmixer stoptimeout 1000 pluginstart empty pluginproc empty no plugin started pluginshow 0 pluginkill 1 plugintimeout 10000 10 seconds pluginforcejvm 0 logfile empty no logging vstmultithreading 1 vstthreadpriority 2 quiet 0 Ret LicenceType initialized determines if module is initialized 1 if initialized 0 else version returns version string version string show shows mixer identical to showmixer outputs if set to 0 output mixers are hidden on startup tracks if set to 0 track mixers are hidden on startup inputs if set to 0 input mixers are hidden on startup topmost if set to 1 mixer window stays on top foreground set to 1 window is forced to the foreground outputs tracks inputs topmost foreground hide hides visualization of allocated channels showtracks shows
58. ing NOTE this parameter is ignored if loopcount is 1 or loopramplen is 0 IMPORTANT NOTE this overlap in crossfade mode changes the total playback length of your buffer to loopcount 1 length loopramplen length name optional name for the data object Is used track view GUI to show names of used vectors Def track vector with all tracks loopcount offset startoffset gain crossfadelen ramplen loopramplen ao 2 D FP O B loopcrossfade loadfile Name loadfile 04a Help loads an audio file to one or more tracks supported formats see PDF see also chapter o documentation NOTE while the device is running you may load more SoundMexPro documentation 48 data to any track at every time However if you load too many data segments file or memory you may produce heavy memory load that may result in dropouts or even crashes Use the command trackload to check how many datasegments are currently pre loaded to the tracks and adjust the speed of loading new data on the fly if necessary On loading new data segments all data that are played not in use any more are removed automatically Par gt filename filename of the audio file to load mandatory NOTE this command does not load the complete file to memory therefore it should be used rather than loadmem on huge files But if files are small and to be played in loop it is recommended to use wavread and loadmem to play data becau
59. ion is the absolute position in time i e recorded samples since the device is running It will be identical to the position if recording to file On each call the number of samples is returned that was specified in command recbufsize Therefore if recgetdata is called before this number of samples is recorded at all zeroes are prepended and the returned position will be negative In subsequent calls to recgetdata you may retrieve overlapping data if you are calling fast and thus the number of new samples n i e samples that were not already retrieved in last call can be calculated by the difference of the two retrieved positions pl and p2 n p2 pl If this number is larger than your recbufsize than you have missed data Otherwise you can copy the new data with respect to the overlap the last recbufsize n samples in the first buffer are identical to the first recbufsize n samples in the second buffer and you may Skip them recmute recmute sets mute status of one or more input channels and returns current status NOTE mute unmute is not ramped NOTE solo status supersedes mute status if solo status of any input is 1 then mute status of all inputs is ignored value vector with mute values 0 for unmute or 1 for mute If no value is specified no mute values are changed current values are returned Either one value must be specified applied to all channels or lengths of mute and input vector must be
60. irect i o For the signal processing task a separate MATLAB process is started to avoid interference between signal processing and other parts of the main task The script MATLAB script DSP interface of SoundMexPro is initialized and configured with multiple options of the command init see also chapter 11 1 The corresponding options are explained here in more detail Option Description pluginstart Name of a MATLAB script to be called on after startup of the separate processing MATLAB process This script is intended for initial time consuming setup of the user defined signal processing scheme Here you may as well read from the main calling MATLAB instance e g by reading a MAT file that the main instance wrote prior to init The called script must implement a function taking three input arguments and returning one value success flag e g function retval plugin start inchannels outchannels samples The passed arguments are inchannels The number of input channels to be expected in calls to the processing script outchannels The number of output channels to be expected in calls to the processing script samples The number of samples per channel to be expected in calls to the processing script These values may be useful e g to create some memory for a filter with the correct size Important note this script must be in the search path of MATLAB to enable the separate processing
61. ith version 2 0 SoundMexPro introduced many new features and a few changes You can find the complete version history of SoundMexPro on the SoundMexPro homepage at http www soundmexpro de download history txt New commands channelname trackname recname symbolic names can be set for tracks output and input channels and these names can be used in all commands for the parameters track output and input respectively besides their indices recvolume sets recording gain tracklen returns total length of loaded data in tracks cleartrack clears data in particular tracks New features for loading sound data file or vector Object gains each loaded object can get it s own gain crossfading between loaded sound objects object ramps each loaded object can have own volume ramps loop ramps each loaded object can have own volume ramps for each loop loop crossfade each loaded object can do a crossfade when looping Other new features VST plugins for recording channels Support for compiled MATLAB script DSP plugins Most commands now allowed while sound output is already running New GUI features Update of wavedata in trackview while running allowed Ctrl left mouse button sets playback position in trackview Mixer now has a variable width Changes in default behaviour Default value for parameter autocleanup in command init is now o Default value for parameter wavedata in co
62. iver are written to audio files one 32 bit float WAV file per output channel Using file to file operation is useful only if you want to run own plugins VST or MATLAB script plugins that are too slow for real time operation If such slow plugins are used with regular soundcard operation xruns dropouts would occur because regular operation is hardware driven i e the soundcard driver calls SoundMexPro when it needs data If you only want to store the output data i e the audio data passed to the output channels in regular mode then you should use the command debugsave rather than using file to file operation In file to file mode you can use all SoundMexPro commands except debugsave to set up you desired scenario configure multilple virtual tracks load files and MATLAB vectors load VST plugins or use the MATLAB script plugin You can set the output filenames with command f2ffilename Afterwards simply call the start command note the parameters of start are ignored in file to file mode Here the main difference between regular operation and file to file mode applies in regular operation the start command returns immediately and you can do asynchronous work in MATLAB check many of the tutorials in ffile to file mode SoundMexPro will process all data and the start command will return after processing is complete Depending on your loadfile and loadmem calls this ma
63. k empty trackload trackload retrieves the number of pending audio data buffers mem or file for all tracks This command is intended for monitoring the current load of a track especially if data are loaded on the fly while the device is running If you load too many data segments file or mem you may produce heavy memory load that may result in dropouts or even crashes So this command can be used to adjust the speed of loading new data on the fly if necessary vector with number of data segments that are currently pending for output on all tracks tracklen tracklen returns vector with total length of all tracks i e position of last sample in each track A value of 1 indicates that an endless loop is running on the particular track vector with lengths of all tracks wait wait waits for output on one or more track to be finished NOTE if a track is specified where an endless loop is running an error is returned track vector with tracks indices or cell array with names to wait for no duplicates allowed timeout timeout value If a value 0 is specified the function returns with an error if output was not finished within value milliseconds SoundMexPro documentation 50 mode output or stop If output is set the command waits until no more output data are pending for the corresponding track s i e it may return slightly before all data were really processed through soundcard If sto
64. l thoroughly It is located in the tutorial subdirectory of the SoundMexPro installation The files named t_ are part of the tutorial the others are helper scripts The file names are chosen if sorted alphabetical to give the tutorial a logical order with an ascending level of complexity using more and more commands of SoundMexPro starting with t 01 basics m In the examples subdirectory you may find some advanced examples that might be useful such as a pair comparison script with cross fade SNR adjustment on the fly and some VST examples The tutorial and the examples are described in detail in chapter 5 pp SoundMexPro documentation 11 3 2 Architecture Output Channels and Virtual Tracks The descriptions in this chapter reference to some SoundMexPro commands that will be described later but they should give you an idea here which commands are important for understanding the basic concept of SoundMexPro The basic idea of SoundMexPro is based on the discrimination between output channels hardware called output channels below and virtual audio data tracks software called tracks where audio data can be loaded to Each track can be connected wired to an output channel and like in a mixing desk multiple tracks can be connected to the same output channel these tracks i e the audio data of these tracks are mixed on the fly to the output channels Each output channel of Sound
65. lding snippets Please read the command reference in chapter 11 for a full description and check the corresponding tutorial scripts The following subsections describe a few special features in more detail These details apply for audio files and MATLAB vectors thus the term audio objects is used in the following for both types of audio data 3 3 1 Loops ramps and crossfades SoundMexPro supports different types of ramps amplitude gain envelopes when loading audio objects Parameter ramplen length of ramp to be applied in the beginning and at the end of the complete object after applying all loops offsets Parameter loopramplen length of ramp to be applied in the beginning and at the end of each loop The figure below shows an example of a gain ramp for an object that was loaded with a loopcount of 3 The dashed lines mark the beginning of a new loop A startoffset o was specified the first loop is shorter A ramplen of x samples and a loopramplen of y samples were specified Additionally SoundMexPro supports two types of crossfades go SoundMexPro documentation 16 Parameter crossfadelen Crossfades between different audio objects the last samples of an audio object are ramped down and added to the first samples of the following audio object ramped up The desired crossfade length has to be specified when loading the second of the two audio objects to be crossfaded The figure below shows an exampl
66. lengthy pluginforcejvm f this parameter is set to 1 the separate processing MATLAB instance is started with Java Virtual Machine JVM It is highly recommended NOT to use this flag since the JVM lowers the performance of plugins significantly Additionally you may have to increase the value of the parameter plugintimeout because the MATLAB startup might be very slow This parameter is ignored for Octave Important note due to performance reasons the separate processing MATLAB instance is started without the Java Virtual Machine by default In this case no GUI commands e g figures are supported allowed in plugin scripts If GUI commands are needed please refer to the parameter pluginforcejvm above During the runtime the main MATLABQ instance that runs SoundMexPro can exchange data with the processing MATLAB instance using the commands pluginsetdata and plugingetdata The command pluginsetdata writes new user data that are passed to the processing script see above and the command plugingetdata retrieves the current user data so that a bidirectional communication can be established NOTE a change in the user data may not be applied immediately it may take a few buffers calls until they reach the processing script For an example please refer to the tutorials t o7 realtime plugin m and the scripts used by the example t o7a x plugin start m and t 07a x plugin proc This tutorial shows a
67. mmands showtracks and updatetracks is now 1 Default GUI command show was removed Command show now is identical to showmixer 2 Installation 2 1 System Requirements SoundMexPro runs on MATLAB 5 3 R11 1 and above or GNU Octave 3 8 and above on Microsoft Windows 95 and above 32 bit and 64 bit There are no special requirements on the computer However the more power your computer has the more tracks devices and DSP plugins can be handled simultaneously without dropouts SoundMexPro runs with every sound card that is shipped with an ASIO driver However H rTech cannot guarantee the support of all features with all sound cards T Me SoundMexPro documentation 7 If you want to use a soundcard that is not shipped with an ASIO driver you may use a universal ASIO driver for WDM e g ASIO4ALL see http www asio4all com or Jack with JackRouter see http jackaudio org If you cannot use one of these universal drivers for any reason you may use the wdm mode of SoundMexPro supporting two output channels only no inputs supported see commands setdrivermodel and getdrivermodel For recommendations on sound cards please contact H rTech by email fax or phone 2 2 Installing SoundMexPro Run SOUNDMEXPRO EXE and follow the installation instructions The following files will be installed on your computer Directory bin libsndfile 1 d11 mpluginmex old dll mpluginmex
68. mped down NOTE ramplen must not exceed half of total play length ramplen lt loopcount length startoffset loopramplen number of samples for fade in and fade out hanning ramp for each loop of object i e the first ramplen samples of each loop are ramped up and the last ramplen samples are ramped down If a startoffset gt 0 is specified then the very first played ramplen samples are ramped up as well NOTE if fileoffset and length are specified then the ramps apply for the snippet defined by these parameters loopcrossfade if this value is set to 1 then a crossfade with a length of loopramplen samples is done on looping NOTE this parameter is ignored if loopcount is 1 or loopramplen is 0 IMPORTANT NOTE this means that the length of each loop will be shorter by loopramplen samples than total sizes file Def gt track vector with all tracks loopcount offset startoffset fileoffset length gain crossfadelen ramplen loopramplen on oOo HB 0 0 O Hh loopcrossfade cleardata Name gt cleardata Help gt clears all loaded audio data and resets positions to zero If device is running command is only allowed if start was called with length set to 0 cleartrack cleartrack clears all loaded audio data on one or more tracks If device is running command is only allowed if start was called with length set to 0 track vector with tracks indices or cell array with names to to be cleared trac
69. n eventually detected clipping e g by stopping the complete script NOTE clipping on the input is defined in SoundMexPro as two subsequent samples with 1 or 1 within one buffer Clipping on the output is checked after applying signal processing and gains to detect clipping directly before D A conversion Clipping on the input is checked before applying any signal processing or gain to detect any clipping after A D conversion 4 2 2 Xruns Dropouts occur in the input or output so called xruns SoundMexPro tries to detect xruns caused e g by too slow DSP processing within the plugin pipe However if the total processor load is very heavy SoundMexPro may not detect xruns They can only be detected if there is enough processing time left to let the soundcard itself send a request for new data The current value can be retrieved at any time with the command xrun and the user may react on eventually detected xruns e g by stopping the complete script Additionally SoundMexPro distinguishes two types of XRuns Processing queue xruns these are dropouts in playback or recording due to slow DSP processing resulting in audible dropouts or dropouts in recorded data Visualization and hard disk recording dropouts these dropouts occur if your hard disk is too slow for writing all data to disk or your computer is too slow to do the visualization of the data if shown at all These xruns result in dropouts in your recording but
70. n neg den ev ee aene es O E ERE e ev er EEEE SEE TETES 25 6 2 The SoundMexPro TrackView csccssssssesssessseseseeeseseseseseseseseseseseeeeeeeseeseeeeeeeeceeeeeeees 26 7 SoundMexPro Realtime DSP Plugins ccccccccececececccecececccececececeeecececececesecesececeseseseeesesesees 27 7 1 Realtime processing with MATLAB SCTIIPtsS cccccccceccecccecececececececececececececeseceeeseeeeeees 27 7 1 1 Using compiled script plugins cc cessssccccececsessseseececececeeseesseeseneeeeceseeseeeseenseess 30 7 2 Realtime processing with VST plugins ccececccccccececececececececececececececececececeeeceeeceeeeeses 30 7 2 14 1 O configuration of VST plugins s sceo ripe RAE VER EXER NEP EXT SvEpUS EEEEHUS FER OP UR FORE Aer EPA RUP 30 7 2 2 VST plugin configuration files eese eeeeeeeeeeeeeee eee eene ener nnn nnns 35 E Macc SoundMexPro documentation 4 723 EB EXEUNTES T m 36 8 ASIO Direct Monitoring ADM cuiconsiesbas COH PRERRNNEEFEGN FEX PPNEEEA UE T DFo RYE FU PERRO RR Eo 2 ORI 36 8 1 Extensions hints for particular sound Cards eese rte rrr rto tin kao tern ko Pelr Rer eda p 36 8 1 1 Mapping inputs to multiple outputs cccecececececcececececececececececececeeeceeeseceeeeeseess 36 Dnus Ouiputeamy pan oMLfOL s sides RR reeni r Esos E e KE Vr UEM DURAM RM RUM rM iN U 37 83 3 ADM Mixer feedback ueteri E Donee Eee EY 37 9 File to file op
71. nd to the plugin To retrieve all available information about a VST plugin including parameters and programs use the command vstquery 7 2 2 VST plugin configuration files The commands vstset and vststore can be used to store or load settings for a VST plugin from a configuration file the command vstload optionally can use configuration files as well The format of configuration files is the standard Windows ini file file format NOTE no spaces allowed with the following sections fields and values Settings This section contains fields used for the O configuration only used by vstload The names of the fields and their meaning are identical to the command line arguments of command vstload Multiple inputs and outputs must be specified as comma separated list NOTE command line arguments supersede configuration file entries Program This section may contain two fields program If it is specified the current program of the plugin is set to the value of this field This field internally calls the SoundMexPro command vstprogram please refer to the command reference below for details programname If it is specified the name of the current program of the plugin is set to the value of this field NOTE this command does not select a program but renames it This field internally calls the SoundMexPro command vstprogramname please refer to the command reference below for details
72. ng for direct I O wiring NOTE successful call to command does not guarantee that command was successfully done in driver Drivers may ignore commands and or parameters that are not supported and return success anyway Please see also the extra ADM chapter in the SoundMexPro manual Par input input channel to monitor 1 monitors all inputs not supported by all drivers output output channel fpr monitoring the input Snippet from original ASIO help Output is the base channel of a stereo channel pair i e output is always an even channel 0 2 If an odd input channel should be monitored and no panning or output routing can be applied the driver has to use the next higher output imply a hard right pan gain to set ranging from 0 inf to 2147483647 12 dB hex Ox7fffffff where 536870912 hex 0x20000000 is 0 dB NOTE the gain values may not be distibuted linearly neither on a dB nor on alinear loudness scale depends on soundcard driver pan to set where 0 is left and 2147483647 hex Ox 7fffffff is right NOTE panning may be implemented different and may depend on output if odd or even channel used see see above Please check out behaviuor of your device flag what to set 0 switches monitoring off 1 switches monitoring on NOTE no other modes are part of the original ASIO interface But some soundcard manufacturers support SoundMexPro documentation 60 more undocumented modes you may simply try
73. nnels cell array with current record file names for all allocated output channels f2ffilename sets one or more file2file filenames for one or more channels and returns current name s NOTE value can only be set if device is stopped If an invalid filename is passed or a filename that is already used by another channel you may get errors on start Default names are f2f wav where is the channel number NOTE file2file files are always overwritten NOTE file2file files are always stored as normalized 32 bit float PCM wave files filename cell array with one or more filenames for file2file data The number of filenames must be identical to the number of channels specified in channel channel vector with channels indices or cell array with names were filenames to be set SoundMexPro documentation 52 04b Def gt channel vector with all allocated output channels Ret gt cell array with current record file names for all allocated output channels 11 4 Recording Commands This table contains commands related to audio recording IMPORTANT NOTE record files are always overwritten Use the recfilename command to change the filenames if necessary NOTE recorded data are always stored in normalized 32 bit float PCM wave files recording Name recording 05a Help returns record status of all allocated input channels Ret vector with zeros and ones denoting corresponding record status i e 1 if ch
74. nt buffer size not sample accurate IMPORTANT NOTE if you use the playposition command to reset current position in pause mode to position X then the command will not return the position you have set but a position Y that is smaller When unpausing the device it will play X Y samples of zeros before the first requested sample at position X is audible Use loadposition to retrieve next audible sample in pause mode instead See also command loadposition position position in samples to set playback position to position 1 position not changed current sample position of device loadposition loadposition returns current loading position of device in samples This is the number of samples loaded up to now therefore higher than the value of playposition It s value is playposition ASIO buffersize numbufs numbufs see init NOTE since ASIO does blockwise audio processing the returned value always is a multiple of the current buffer size not sample accurate current loading position of device volume volume sets volume and returns current volume of output channels value vector with volumes linear gains If no value is specified no volume is changed current volumes are returned Either one volume must be specified applied to all channels or lengths of volume and channel vector must be identical gains applied in corresponding order to specified channels NOTE this volume is the m
75. o virtual tracks input plugin is loaded as recording plugin it is plugged into input channels row vector with input channels hardware channels or tracks plugin must support number of inputs A value of 1 configures a plugin input to be used as recurse input see parameters recursechannel and recursepos below row vector with output channels hardware channels or tracks plugin must support number of outputs If empty input vector is used input output position vertical position Each channel may contain five vertical plugins that are called subsequently recursechannel An input of a plugin can be configured to receive so called recurse data data rather than regular input audio data from a channel or a track This feature is intended for recursion e g for adaptive filter plugins that need a plugin output as an input To configure a plugins input for this purpose a value of 1 must be specified for that plugin input in the parameter vector input see above The parameter vectors recursechannel and recursepos configure the source for this plugin input by specifying the channel track or output channel depending on plugin type and the vertical position see parameter position where the data are copied from For a detailed example see the manual of SoundMexPro NOTE if the position of the source recursepos is the same or higher than this plugin s position then the source is behind the input T
76. ol is closed again driver name or index of ASIO driver driver 0 trackmap Name trackmap Help sets track mapping and returns current mapping see also chapters 3 2 Par track vector with track mapping The vector must have an entry for every initialized track see parameter track of command init specifying the output channel indices or cell array with names on which to playback the track data Data are loaded to tracks with commands loadmem and loadfile The data of all tracks are applied to the data of the corresponding output channel i e if more than one track is mapped to the same output the signals are added or multiplied and you may have to take care for clipping Ret vector with current track mapping trackmode Name trackmode Help sets mode and returns current mode of tracks SoundMexPro documentation 44 Par gt mode vector with mode values If no value is specified no volume is changed current modes are returned Either one mode must be specified applied to all tracks or lengths of mode vector and track vector must be identical modes applied in corresponding order to specified tracks Valid modes are 0 sample values of tracks are added to the output channel where they are mapped to output channel data are multiplied with the track data NOTE the multiplication is not done with the final total data but with the data processed added from tracks with a lower index
77. onding order to specified channels 1 sets enables debug saving a file named out wav is created where is the channel number The output data are saved to that file before sending them to soundcard NOTE volume and any ramps or applied after saving 0 disables debug saving NOTE this command is not available in file2file operation channel vector with channels indices or cell array with names to apply mode no duplicates allowed value current modes no changes channel vector with all allocated channels vector with current debug modes for all allocated channels debugfilename debugfilename sets one or more debug filenames for one or more channels and returns current name s NOTE value can only be set if device is stopped If an invalid filename is passed or a filename that is already used by another channel you may get errors on start Default names are out wav where is the channel number NOTE debug files are always overwritten NOTE debug files are always stored as normalized 32 bit float PCM wave files NOTE never write files directly to network drives or other slow drives This may cause dropouts xruns filename cell array with one or more filenames for debug data The number of filenames must be identical to the number of channels specified in channel channel vector with channels indices or cell array with names were filenames to be set channel vector with all allocated output cha
78. ore tracks and returns current status NOTE muting unmuting is not ramped NOTE solo status supersedes mute status if solo status of any track is 1 then mute status of all tracks is ignored value vector with solo values 0 for unsolo or 1 for solo If no value is specified no solo values are changed current values are returned Either one value must be Specified applied to all tracks or lengths of solo and track vector must be identical values applied in corresponding order to specified tracks track vector with tracks indices or cell array with names to apply values no duplicates allowed value current solo values no changes track vector with all tracks vector with current solo values for all tracks channelsolo channelsolo sets solo status of one or more output channels and returns current Status NOTE muting unmuting is not ramped NOTE solo status supersedes mute status if solo status of any output is 1 then mute status of all outputs is ignored value vector with solo values 0 for unsolo or 1 for solo If no value is specified no solo values are changed current values are returned Either one value must be Specified applied to all channels or lengths of solo and output vector must be identical values applied in corresponding order to specified channels output vector with output channels indices or cell array with names to apply values no duplicates allowed Def value current solo valu
79. ould add the BIN directory of your SoundMexPro installation e g C SoundMexPro bin to your MATLAB path NOTE if you want to use SoundMexPro on MATLAB 7 1 or below you have to rename the files bin soundmexpro old dil to bin soundmexpro dll and bin mpluginmex old dll to bin mpluginmex dll NOTE Do not play files from or record files to network drives 2 2 1 Accessing SoundMexPro help from MATLAB If the BIN directory is part of the MATLAB search path you can access the HTML help of SoundMexPro from the MATLAB help browser MATLAB version gt 7 0 Call the doc command and select SoundMexPro from the content pane Note that you need to restart MATLAB after adding the BIN directory to the search path before SoundMexPro will be listed on the content pane To call the HTML help of SoundMexPro directly from MATLAB please use the web command rather than doc SoundMexPro this not supported by all MATLAB versions web c soundmexpro manual html soundmexpro html or web soundmexpro html helpbrowser NOTE the second syntax only works if you have added the Manual HTML path of SoundMexPro to the MATLAB search path If you want to access the HTML help through the MATLAB command doc SoundMexPro on MATLAB versions older than 7 0 please copy the content of the subfolder Manual HTML from your SoundMexPro Installation to the directory MATLAB path gt help tec
80. owing number of VST plugins that require the VST license At the moment all plugins can be loaded with the VST license as well but this may be changed at any time without notification tiie SoundMexPro documentation 38 11 SoundMexPro Command Reference The tables below show a list of all available commands sorted by functionality The following abbreviations are used in the column Description Name gt Name of the command Help gt Help text Par Parameter list Def Default values of Par Ret Return values The return values ar described on separate lines where each value is returned as separated outarg In column Tut Tutorial you can find the tutorial number where the corresponding command or special features parameters of the command are introduced The number in that column is part of the filename For example the number o4a corresponds to the file t o4a play wait m in the tutorial subdirectory 11 1 General Commands This table contains general commands e g online help initialization Command help helpa about setdrivermodel getdrivermodel Init see also chapters 3 2 and 3 3 2 Description Tut Name gt help 01 Help gt prints help on command or command list Ret gt command help Without argument a command list is printed in logical order Name gt helpa Help gt prints help on command or command list Ret gt command help Wit
81. p is set then the command waits until the device is stopped automatically after playback is done see parameters of command start or if it is stopped by command stop e g from GUI If stop is specified then track is neglected Def track vector with all tracks timeout 0 no timeout i e endless waiting mode output playing playing returns play status of all tracks vector with zeros and ones denoting corresponding play status i e 1 if a track currently is playing data or 0 if not NOTE the return value does not show if the device is running If a channel is running but playing zeroes because no data were loaded the return value for the track will be 0 To check if the device is still running use the command started NOTE this command will return 0 immediately after the data are to the driver completely If you want to wait for the playback to be finished in autostop mode see parameter length for command start when setting values other than 0 then you should used the command started to wait for device to be stopped playposition playposition Sets and returns current play position of device in samples audible samples Setting the play position is only allowed if parameter autocleardata was set to 0 in command init and if device is paused with command pause NOTE since ASIO does blockwise audio processing the returned value always is a multiple of the curre
82. plerate can be used only files with this samplerate can be played output channels to allocate row vector or number of channels to use for file2file operation scalar value NOTE after initialization the allocated channels are enumerated starting with 0 If 1 2 4 is specified as output channels you can access them in later commands only with indices 0 1 or 2 respectively If 1 is specified no output channels are used if all is specified all available output channels are used input channels to allocate row vector NOTE after initialization the allocated channels are enumerated starting with 0 If 1 2 4 is specified as input channels you can access them in later commands only with indices 0 1 or 2 respectively If 1 is specified no input channels are used if all is specified all available input channels are used NOTE recorded data are always stored in normalized 32 bit float PCM wave files NOTE never store record files directly on network drives or other slow drives This may cause dropouts xruns NOTE ignored for file2file operation number of virtual output tracks to be used Each output track is connected mapped to one output channels This mapping can be changed with the command trackmap see also command trackmap for a description how multiple track data are played on output channels On init the mapping is done circular i e track 0 is mapped to channel 0 track 1 is mapped to channel 1
83. processed data Ifa channel is not used in any plugin then the original input data are preserved If the same channel is used as output for another plugin then this channel will contain a sum of the original channel data and the processed output data of the plugin Each plugin within one horizontal position is processed in a separate thread to benefit from the calculating power of multiple processors This means that input data are passed to all plugins of one layer e g position o plugins 1 and 2 Then the processing is performed independently in different threads The data are synchronized again after each layer i e SoundMexPro has to wait until all plugins of one layer have completed their processing to keep the time line consistent LL Nes SoundMexPro documentation 34 before passing the data processed by first layer plugins to the next layer and so on To disable multi threading within the VST host use the vstmultithreading parameter of command init A VST plugin can have different programs and parameters that may be changed on runtime A program can be selected by name a value of a parameter can be set by name as well valid values are between o and 1 the plugin may convert this value internally and may show such converted values on its editor but setting is only allowed within this range These programs and parameters are specific for each plugin SoundMexPro simply passes the values from a
84. r is ignored in file2file mode pause if set to 1 device is paused rather than stopped value current thresholds no changes 0 on startup mode 1 channel vector with all allocated input channels length 1 If NO output channels are specified on init i e 1 for output then default is 0 pause 0 current threshold value current threshold mode started checks if device was started is still running NOTE this command only checks if the ASIO device runs it does not check if data are playing on any channel see playing 1 if device is started 0 else stop Stops device and clears loaded data pause Sets pause status of device playback and record and returns current status value 1 pauses device or 0 unpauses device value current value no change 1 if device is paused 0 else mute sets mute status and returns current status NOTE this command mutes all output channels globally using a ramp of length ramplen argument of command init See also commands channelmute and trackmute and recmute value 1 mutes output or 0 unmutes output value current value no change 1 if device is muted 0 else trackmute sets mute status of one or more tracks and returns current status NOTE muting unmuting is not ramped NOTE solo status supersedes mute status if solo status of any SoundMexPro documentation track is 1 then mute status of all tracks i
85. r medical devices or weapons systems in which the failure of the Software could lead directly to death personal injury or severe physical or environmental damage High Risk Activities H rTech gGmbH and its suppliers specifically disclaim any express or implied warranty of fitness for High Risk Activities OWNERSHIP AND COPYRIGHT This Software is owned by H rTech gGmbH or its suppliers and is protected by copyright law and international copyright treaty Therefore you must treat this Software like any other copyrighted material You acknowledge that no title to the intellectual property in the Software is transferred to you Title ownership rights and intellectual property rights in and to the Software shall remain in H rTech gGmbH LICENSE GRANT Subject to the license terms H rTech gGmbH hereby grants you a non exclusive non transferable except under the terms below license to install and to use the Software under the terms of this license Except as provided in this license agreement you may not transfer rent lease lend copy modify translate sublicense time share or electronically transmit the Software You may only either make one copy of the Software solely for backup or archival purposes or transfer the Software to a single hard disk provided you keep the original solely for backup or archival purposes You agree not to modify the Software or attempt to decipher de compile disassemble or reverse engineer the Softwa
86. re except to the extent applicable laws specifically prohibit such restriction LICENSE TRANSFER You may transfer your license and the rights granted in the license to a third party only if a the third party agrees to this license agreement b you completely uninstall and delete all copies of this Software c all parts of the Software and its distribution are transferred to the third party and d the transfer includes the current version and all prior versions of the Software pe SoundMexPro documentation 2 DISCLAIMER OF WARRANTY THIS SOFTWARE IS SOLD AS IS AND WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED IMPLIED OR STATUTORY INCLUDING BUT WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NONINFRINGEMENT OF THIRD PARTY RIGHTS MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH NON CRITICAL DATA BEFORE RELYING ON IT THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM ANY LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE Under and restricted by the above terms H rTech gGmbH warrants that the Software as updated and when properly used will perform substantially in accordance with its accompanying documentation and the Software media will be free from defects in materials and workmanship The limited warranty is void if the Software f
87. refer to the tutorial script t o8 async errors m that shows how to detect such errors 5 Tutorial Examples and Scenarios This chapter contains a description of the SoundMexPro tutorial a growing collection of examples special scenarios and extended explanations to particular commands This chapter uses many of the SoundMexPro commands Please refer to the command reference in chapter 11 for help on particular commands 5 1 The SoundMexPro Tutorial SoundMexPro is shipped with a tutorial It is highly recommended to examine the tutorial thoroughly It is located in the tutorial subdirectory of the SoundMexPro installation The files named t_ are part of the tutorial the others are helper scripts The file names are chosen if sorted alphabetical to give the tutorial a logical order with an ascending level of complexity using more and more commands of SoundMexPro NOTE scripts containing x in their name are used by the tutorials described in the table below and should not be called directly Filename Description t oo setup tutorial m Helper script to select a sound card driver and sound card channels to be used for the tutorial and examples t oob init tutorial m Helper script that reads settings created with t oo setup tutorial in each tutorial file t 01 basics m This example shows very basic commands initialization and track mapping using the online help retrieving version information and
88. rs Figure 13 shows a simple example for recursion within one channel SoundMexPro channel o Position o Position 1 Figure 13 Recursion within VST plugins in SoundMexPro Ade SoundMexPro documentation 33 The configuration for these two plugins would be oe soundmexpro vstload command name filename adaptive dll filename of plugin binary evoe Unser E plugin type here track plugin timoti tya 9 p asc tracks to read data from reocunrsechannel Ol recursion source channel recursepos EIS recursion source position Kout pitean oo tracks to write processed data to oe soundmexpro vstload command name filename other dll oo filename of plugin binary oe Uwe Lr reel plugin type here track plugin ae Valinjoue o 9 y tracks to read data from Tomoe a IO sac tracks to write processed data to Two inputs are defined the first uses channel o i e regular audio data from SoundMexPro channel o The second is configured for recursion input 1 The parameters recursechannel and recursepos define the source for this channel it is channel o within the plugins data flow and position 1 i e SoundMexPro channel o AFTER processing within the second vertical plugin position position 1 and thus the output of the second plugin in this example Important note usually such recursions are used for recu
89. rsive filters i e a plugin needs data from later processing steps e g to realize an adaptive filter as in this example Thus if the data source recursepos of a plugin is located BEHIND the plugin itself then the plugin will always receive the data from the last processing block in the first call to the processing it will contain zeroes in the second it will contain the output of the second plugin from the first call and so on NOTE this type of recursive wiring usually needs plugins that know or need recursive data respectively Please check example ood where an artificial usage of recursion is demonstrated using the simple gain plugin shipped with SoundMexPro After loading and configuring multiple plugins SoundMexPro processes the data with the following processing scheme f fewer inputs are specified than available for a particular plugin SoundMexPro passes zeros in the unused channel s to the plugin If fewer outputs are specified than available for a particular plugin SoundMexPro ignores the output from unused channel s of the plugin All plugins within one vertical position receive the identical input data Ifa plugin s input s are configured for recursion the corresponding data are copied to the plugin s input s Jfachannelis used in any plugin of a vertical position layer then the original input data are cleared after processing all plugins of a layer this channel will contain only
90. rst output channel second track to second output channel and so on In this example six tracks and three output channels were specified the tracks are mapped circular to the available output channels Circular here means that a track with number Tracklndex is mapped to output channel number Channellndex calculated by ChannellIndex mod TrackIndex TotalNumberOfOutputChannels In this example the tracks o and 3 are connected to output channel o tracks 1 and 4 are connected to output channel 1 and tracks 2 and 5 are connected to output channel 2 default mapping after init Note this mapping does not yet fit our requirements for the example This default mapping can be changed with the command trackmap to match the example from the requirements map route first two tracks to channel 0 next thr tracks to channel 1 and sixth track to channel 2 soundmexpro trackmap E command name Janet reg TE TECH e track map to set i Now the wiring is complete and matches exactly the configuration shown in e 1 The volume linear gain of each track can be adjusted with the command trackvolume the final master volume of an output channel additionally can be adjusted using the command volume The next step is to load audio data files or MATLAB vectors to the tracks green boxes in using the loadfile or loadmem command respectively The different number of
91. s t o4d play mark buttons m Shows usage of the highly specialized command setbutton for highlighting buttons on a MATLAB GUI synchronized with particular sample positions of the sound output t o4e play mute pause m Muting pausing and soloing mute all other channels of channels and tracks t_oaf_play_startthreshold m Start device threshold driven signal on input t 05a rec standard m Introduces recording to file t o5b rec threshold length m Shows how to trigger recording by a threshold value recording starts after threshold is exceeded in input audio data and recording of predefined number of samples t o5c rec getlivedata m Demonstrates how to get recorded data snippets live to MATLAB vectors e g for online analysis t 06 direct io m t 07a realtime plugin m Shows how to do direct I O through SoundMexPro Maybe combined with later plugin tutorials to do realtime DSP Introduces the realtime MATLAB script plugins in the time domain Easy example where audio data are processed block by block in realtime during output t 07b realtime plugin spec m Introduces the realtime MATLAB script plugins in the frequency domain Uses the STFT scripts stftinit m and stft m BIN directory shipped with SoundMexPro Simple implementation of one function t 07b x stft userfcn m to process spectra block by block in realtime during output t 08 async errors m
92. s for recording data The number of filenames must be identical to the number of channels specified in channel channel vector with channels indices or cell array with names were filenames to be set channel vector with all allocated input channels cell array with current record file names for all allocated input channels recpause recpause sets recording pause status of one or more channels and returns current recording pause status NOTE this only pauses recording to file recording to buffer for retrieving record data with command recgetdata is always enabled So this command may be used also to disable recording to file completely NOTE setting recpause to 1 does not close the recording file it only SoundMexPro documentation 53 recposition recthreshold recstarted reclength Par gt Def gt Ret disables writing to it temporarily If you want to read the file in pause mode you have to change the current recfilename in recpause mode with command recfilename this will close the file s value vector with 1 pauses record of channel or 0 resumes recording channel vector with channels indices or cell array with names were values to apply to value current values no change channel vector with all allocated input channels vector with current recording pause status for all allocated input channels recposition returns record position of all allocated output channels
93. s ignored Par value vector with mute values 0 for unmute or 1 for mute If no value is specified no mute values are changed current values are returned Either one value must be Specified applied to all tracks or lengths of mute and track vector must be identical values applied in corresponding order to specified tracks track vector with tracks indices or cell array with names to apply values no duplicates allowed Def value current mute values no changes track vector with all tracks Ret vector with current mute values for all tracks channelmute channelmute sets mute status of one or more output channels and returns current status NOTE muting unmuting is not ramped NOTE solo status supersedes mute status if solo status of any output is 1 then mute status of all outputs is ignored Par value vector with mute values 0 for unmute or 1 for mute If no value is specified no mute values are changed current values are returned Either one value must be specified applied to all channels or lengths of mute and output vector must be identical values applied in corresponding order to specified channels output vector with output channels indices or cell array with names to apply values no duplicates allowed Def value current mute values no changes output vector with all output channels Ret vector with current mute values for all output channels tracksolo tracksolo sets solo status of one or m
94. scription pdf 5 3 Using SoundMexPro without MATLAB 5 3 1 Using the SoundDllProLoader A simple loader SoundDllProLoader exe is shipped with SoundMexPro It is designed to load the DLL SoundDIlIPro dll including the main functions of SoundMexPro for using it without MATLAB In this way it is possible to implement SoundMexPro Tasks on computers that do not run MATLAB The loader is described in detail in the separate manual SoundDllProLoader pdf an example can be found in the examples subdirectory 5 3 2 Programming Interface API A simple programming interface to the main SoundMexPro DLL SoundDIIPro dll is available to call SoundMexPro directly from your own code Please refer to the separate manual SoundMexPro Interface Description pdP for details and check the corresponding example in examples subdirectory 6 SoundMexPro GUI interfaces 6 1 The SoundMexPro Mixer The commands show and showmixer show a mixer interface with volume mute and solo controls for all tracks output and input channels Figure 8 Clicking the vertical gray bar left of the tracks outputs and inputs section respectively toggles visibility of the corresponding section Below the track number the SoundMexPro output channel and input channel indices are shown if any are mapped to the track here only track 1 has an input mapped with command iostatus Below the channel number the ASIO channel name of the corresponding input or
95. se it is much more efficient to read from memory than to read from file on the fly IMPORTANT NOTE the channels of multichannel audio files are loaded aligned to the specified tracks i e there may be zeros prepended to one or more channels if necessary vector with tracks indices or cell array with names were data to be played no duplicates 0 allowed The number of tracks must be a multiple of the number of channels of the wave file If tracks devided by channels is 1 the data are loaded circular to the specified tracks e g loading a wave file with two channels and specifying 01 4 7 in track then the file channels are loaded as follows channel track 0 0 channel 1 gt track 1 0 channel track 4 channel 1 gt track 7 or loading a mono file with an empty track argument will load that data to all tracks For a wave file channel that should not be played on any track specify a negative value This value is ignored if output in command init was 1 loopcount number of times the data are to be played NOTE 0 is an endless loop offset number of zero samples to be played in the beginning startoffset number of samples to be skipped from data when playing the first loop A value of 1 selects a random startoffset NOTE the samples of the file to be used are determined by the parameters fileoffset and filelength fileoffset sets the number of samples to be skipped from the start of the
96. showing hiding the standard GUI t o2 device info m Shows how to retrieve information about installed devices sound cards and their available channels and properties Additionally the usage of symbolic names for tracks is introduced t o2b config tools m Shows usage of the tool scripts soundmexpro_showdevs m soundmexpro showcfg m LL Ne SoundMexPro documentation 22 and soundmexpro_trackmap m located in the BIN subdirectory of SoundMexPro These scripts may be usefull to check available hardware or your current SoundMexPro configuration after init and to generate command parameters for init or trackmap respectively t 03 error handling m Demonstrates standard and user defined error handling t o4 play loops crossfades m Shows special parameters to be used in commands loadfile and loadmem concerning looping and crossfading of sound objects t o4a playback wait m Playing files and vectors in different conditions blocking non blocking play parts snippets t o4b play mix volume m This example introduces the usage of multiple tracks for mixing audio data on the fly including volume adjustment mixing ration Additionally the usage of the mixer and the trackview GUI are shown t oAc play con stim gen m Demonstration of online stimulus generation audio data are added to the output while the device is running on the fly with respect to underrun
97. specified tracks If more than one channel is specified then the number of tracks must be identical and the input channels are mapped to one track each in the specified order vector with tracks indices or cell array with names for mapping no duplicates allowed The samples of the specified input channel are added to all specified tracks Passing 1 clears mapping for specified input channel Ret gt vector containing tracks where the samples from the input channel are added to NOTE this value is only returned if one input channel is specified Name gt setbutton 04d Help gt enables button marking synchronized with playback NOTE after marking and unmarking a particular button the marking information is resetted To use the same marking information again you have to call setbutton again Par gt handle window handle of the button startpos starting point in samples length marking length in samples channel output channel with mix data to calculate samples Name gt dspload 07a Help returns current and maximum dsp load that occurred The dsp load is the time consumed within a block for signal processing compared to total available computing time for a block in percent Ret current dsp load maximum dsp load since startup or last call to dsploadreset ame dsploadreset 07a Help resets the dsp load maximum value see command dspload Name adm 10 Help interface to ASIO Direct Monitori
98. t the driver calls the sound application when it needs new audio data If this call happens the data are needed immediately and if the operating system or your MATLAB task is very busy at the moment then audible dropouts so called xruns may occur First of all an application must be capable to provide audio data for the driver at a sufficient speed i e on average the processing generation of one audio data block must not take longer than the output of a block of same size If the processing is too slow then xruns are unavoidable see example in tutorial t o7a realtime plugin the processing scheme has to be optimized or offline processing has to be done But xruns may occur sometimes even if the processing is fast enough it may happen that the operating system or your MATLAB script produces heavy load temporarily exactly at the moment when audio data are requested by the driver Then xruns will occur if no so called software buffering is done Software buffering stores a particular number of processed audio data blocks for passing them to the driver immediately In this way some buffers are filled pre processed when the processor load is not extremely high and on temporary heavy load there are always a few processed buffers available that only have to be passed to the driver SoundMexPro supports software buffering The number of buffers to be used is specified in the parameter numbufs in command init defaul
99. t be specified applied to all channels or lengths of volume and channel vector must be identical gains applied in corresponding order to specified channels NOTE this volume is the master volume i e it is applied before all signal processing and mixing as a linear factor to each sample IMPORTANT NOTES this volume is applied to each recorded sample BEFORE any signal processing mixing aor threshold determination is done see also command recthreshold Clipping is checked BEFORE applying the volume This gain is NOT ramped channel vector with input channels indices or cell array with names to apply volume to no duplicates allowed value current volumes no changes channel vector with all allocated channels vector with current volumes for all allocated channels 11 5 MATLAB script DSP commands This table contains commands related to communication with MATLAB DSP plugins NOTE these commands are only available with a DPS or VST license Name pluginsetdata 07a Command pluginsetdata Help sets current plugin user data Par data matrix with user data mandatory A matrix with the n columns and 100 rows must be specified where n is the number of allocated input or output channels respectively input or output to set input or output user data output plugingetdata plugingetdata retrieves current plugin user data mode input or output to retrieve input or output user data
100. t is 10 buffers Software buffering will cause additional delay for the signal output For applications where only sound output or recording is done this usually can be neglected it does not interfere with standard playback recording tasks you may find a few additional buffers of zeros in recorded files But in applications where SoundMexPro is used as DSP Engine i e data from the inputs are processed and played back directly command iostatus then a minimum delay may be desirable The minimum theoretical delay a ASIO driver will be able to provide is Dmin 2 ASIOBufferSize HardwareSpecific DriverSpecific where pe SoundMexPro documentation 19 ASIOBufferSize buffer size that can be selected in the driver manufacturers soundcard dialog see command controlpanel HardwareSpecific additional delay form hardware e g anti aliasing filters of D A converter DriverSpecific any delay caused by the particular implementation of the driver itself The total delay in SoundMexPro will be Diot D44 numbufs ASIOBufferSize Thus you can minimize the delay by decreasing the ASIO buffer size and or decreasing the number of used software buffers In both cases the risk for the occurrence of xruns will increase 3 4 1 Sound card constraints minimum delay Theoretically the minimum I O delay can be achieved by disabling software buffering i e setting numbufs to zero in command init However some so
101. uffered in memory and can be retrieved with command recgetdata NOTE values smaller than the current buffersize of the device are adjusted to that buffersize except 0 which disables buffering Either one value must be specified applied to all channels or lengths of value vector and channel vector must be identical buffer size applied in corresponding order to specified channels NOTE the requested buffer size has to be allocated from memory for each recording channel So take care that not more memory is requested than available In general more than a few minutes should not be set as buffer size channel vector with channels indices or cell array with names to apply buffer sizes to no duplicates allowed value current record buffer sizes no changes 0 on startup channel vector with all allocated channels vector with record buffer size for all allocated input channels recgetdata recgetdata returns record data channel vector with channels indices or cell array with names to retrieve data from no duplicates allowed NOTE data from multiple channels with different recbufsizes set with recbufsize cannot be retrieved with a single command and must be retrieved subsequently channel vector with all allocated channels matrix with columns containing record data from channels length is set by recbufsize command absolute record sample position of first sample in returned matrix IMPORTANT NOTE this returned record sample posit
102. umber of xruns and current and maximum used DSP time in percent DSP CURRENT MAXIMUM This TrackView is very useful when developing new scripts experiments measurement paradigms In this view you may check that all data are loaded as expected to the tracks especially when you are using multiple mixing tracks and that the final setup is as expected 7 SoundMexPro Realtime DSP Plugins SoundMexPro supports realtime block by block signal processing with two types of plugins Processing can be implemented either with MATLAB scripts or as high performance VST plugins Steinberg Virtual Studio Technology for more costly calculations and time critical applications 7 1 Realtime processing with MATLAB scripts SoundMexPro supports the MATLAB script based implementation of user defined signal processing in realtime i e during playback and recording For this purpose a user defined MATLAB script containing a processing function is called for each data block The samples of M Je SoundMexPro documentation 27 all input and output channels are passed to the script before passed to the driver or directly after receiving them from the driver respectively The script may manipulate those data before returning them as output arguments of the function back to SoundMexPro Important note manipulations of the input record data are not recorded to disk but the input data may be used to copy apply them to output data e g for d
103. und card drivers are introducing two buffers with zeros in the beginning by mistake when no software buffering but a separate processing thread is used for ASIO insiders the driver starts the output of its buffers immediately after the buffer switch returns instead of waiting for the ASIOOutputReady command For these soundcards the minimum delay is D 2D ASIOBufferSize This can be achieved by setting numbufs to 1 in command init To check if your sound card is concerned by this problem you have to measure the delay and compare the delay when setting numbufs to 1 and setting numbufs to zero Most drivers of the sound cards from RME are affected by this problem 3 5 Supported audio file formats SoundMexPro uses the library libsndfile for reading audio files It supports a huge number of audio formats except for MP3 Amongst others the following formats are supported Microsoft WAV Ogg Vorbis Sun DEC NeXT AU SND Commodore Amiga IFF Creative VOC SoundForge W64 GNU Octave 2 0 2 1 MAT4 MAT5 FLAC For a complete list of supported formats please refer to the libsndfile homepage http www mega nerd com libsndfile Recorded data are always stored as normalized single channel 32bit PCM wave files one file per channel pe SoundMexPro documentation 20 4 Error Handling in SoundMexPro When trying to generate clean and stable programming code with any programming or Scripting
104. undMexPro channels to be connected to the plugins inputs parameter output specifies which SoundMexPro channels to be connected to the plugins outputs parameter position specifies the vertical position of the plugin see below Figure 10 shows a sample routing of a VST Plugin We assume that this dummy Channel Gain plugin has two inputs and two outputs The processing scheme of this plugin simply applies a gain to the data SoundMexPro channel O SoundMexPro channel 1 SoundMexPro channel 3 SoundMexPro channel 2 p Figure 10 Sample for the O configuration routing of one VST Plugin The I O configuration in the vstload command for this example would be soundmexpro vstload command name filename plugin dll filename of plugin binary oe oo oe newioe Viger Valine 9 Bil gue il 2 i plugin type here track plugin tracks to read data from o oe tracks to write processed data to The next example uses different tracks for the inputs and outputs The example uses a total of four tracks The routing of the vstload command will result in a complete processing scheme within the SoundMexPro tracks as shown in Figure 11 NOTE in the following the signal flow is always from top to bottom SoundMexPro documentation 31 Track O Track 1 Track 2 Track 3 This example is implemented in the tutorial script t ooa vst simple m usin
105. uptut channels vector with names of allocated input channels getproperties returns current samplerate and buffer size samples of current driverm a list of supported samplerates and uses sound format NOTE before the device is running i e start was called the samplerate may differ from the sample rate that was specified in command init some drivers switch it not before device start If switching to specified sample rate is not successful in command start it will fail with a corresponding error message NOTE the list of supported samplerates may not be complete it is generated by asking the driver if a particular samplerate is supported Some drivers return true even if starting that samplerate will fail e g due to a samplerate lock by driver Settings dialog or external hardware Some drivers may return only one samplerate the current one even if others are supported The following samplerates are checked 8000 11025 16000 22050 32000 44100 48000 88200 96000 176400 192000 352800 384000 samplerate bufsize supported samplerates description of currently used sound format of device controlpanel shows own control panel of an ASIO driver OTE if SoundMexPro is already initialized no driver must be specified the current driver is called NOTE command may raise an error for some drivers if SoundMexPro is already initialized NOTE for some drivers this command may not return before the contr
106. vely If you hold a shift key when clicking a mute or solo button the corresponding action is performed exclusively e g the corresponding channel is muted and all others are unmuted Important note the current volume in dB is shown below the sliders The slider range is limited from 6 dB to 90 dB the switches to inf You may set e g higher volumes with the command trackvolume and the correct value will be shown below the slider But if the slider is moved afterwards the volume will switch into the slider range again The status bar contains information about the device status number of xruns and current and maximum used DSP time in percent DSP CURRENT MAXIMUM 6 2 The SoundMexPro TrackView Since version 1 1 0 3 SoundMexPro supports a so called TrackView commands showtracks and updatetracks It shows a simple visualization of all tracks with their loaded files and vectors An example view with four tracks from tutorial o4b is shown in Figure 9 The wavedata are only plotted if the optional parameter wavedata of the commands is set to 1 default This may take a while Hit Esc to cancel the visualization Use View gt Refresh from the main menu to recalculate the wave data tpg SoundMexPro documentation 26 A time scale is shown at the top You can switch the scale so use a sample scale or a time scale with the context menu right mouse click on the scale or
107. visualization of files vectors in tracks This view is especially intended to check the setup of your experiment pardigm i e if everything is loaded located as expected During playback a cursor shows the current position NOTE command does call updatetracks internally so there is no need to call updatetracks directly after showtracks topmost if set to 1 track window stays on top foreground if set to 1 window is forced to the foreground wavedata if set to 1 waveforms are painted as well NOTE this might take quite a while topmost 0 foreground 1 wavedata 1 hidetracks hides visualization of files vectors in tracks updatetracks updates visualization of files vectors in tracks NOTE this command must be called to have the loaded files and vectors up to date It is recommended to call it directly before play wavedata if set to 1 waveforms are painted as well NOTE this might take quite a while wavedata 1i showmixer shows mixer identical to show outputs if set to 0 output mixers are hidden on startup tracks if set to 0 track mixers are hidden on startup inputs if set to 0 input mixers are hidden on startup topmost if set to 1 mixer window stays on top foreground if set to 1 window is forced to the foreground outputs I tracks 1 inputs 1 SoundMexPro documentation o nn o nn o nn o nn 42 topmost 0 foreground 1 hidemixer hidemix
108. xpro loadfile command name UU tgutrenamcs UE Weel TO D e VLegpcouimne I name of wavefile tracks where to play file o o9 oe play it 1 time In this case SoundMexPro automatically inserts zeros into track 1 pink box to keep the channels of file 4 aligned If you want to load the two channels of file 4 in such a Scenario unaligned you have to do two subsequent calls to command loadfile to load the two channels separately load first file channel to track 0 second file channel neglected by specifying a negative value pA 2 soundmexpro loadfile command name Vien lepine Vita ted creck pr Tiooaxcouime db name of wavefile tracks where to play file oe o oe oce play it 1 time load second file channel to track 1 first file channel neglected by specifying a negative value soundmexpro loadfile command name iene Vita ted reck i wi name of wavefile tracks where to play file oe o ge oce Tilooacouine dL play it 1 time SoundMexPro documentation 18 This leads to the following data status in the two tracks virtual playback i cursor gt I vector 2 file 4 channel 1 3 4 Buffer configuration When playing sound through a soundcard using the ASIO interface audio data are streamed to the soundcard driver i e buffers with audio data are passed to the driver on reques
109. y take a while Afterwards the command cleardata is called automatically See tutorial t 11a file2file m for an example 10 SoundMexPro Versions SoundMexPro is shipped with different licenses with different registration fees The current price list is available from the SoundMexPro homepage http www soundmexpro de 10 1 SoundMexPro The standard version of SoundMexPro supports all commands described in chapter o except the commands recbufsize and recgetdata Furthermore no DSP plugins are supported no script based plugin and no VST plugins pe SoundMexPro documentation 37 10 2 SoundMexPro DSP The DSP version of SoundMexPro supports all commands of the standard version and adds the following DSP features recorded data can be queried from MATLAB while recording is running see commands recbufsize and recgetdata the SoundMexPro realtime DSP Plugin Pipe can be used for script based audio processing see commands corresponding options of command init and commands plugingetdata and pluginsetdata 10 3 SoundMexPro VST The VST version of SoundMexPro supports all commands of the DSP version and adds the following features loading of plugins using the Steinberg Virtual Studio Technology VST interface into track and or master signal data flow 10 4 SoundMexPro VST The VST version of SoundMexPro supports all commands of the VST version SoundMexPro is shipped with a gr
110. ype master position 0 Ret name of current program vstparam vstparam sets and retrieves one or more parameter values of a VST plugin type type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried input one of the plugins input channels specified when loading it with vstload position vertical position of plugin to query parameter parameter name s to set cell array If empty all parameters are queried set value vector with values for parameters All values must be between 0 0 and 1 0 If empty values are not changed otherwise length must be identical to length of parameter cell array type master position 0 cell array with queried parameter names current values of queried parameters vstset vstset sets and retrieves program and or parameters of VST plugin by values in a config file type type of plugin to query Allowed types are master master plugin is queried track track plugin is queried input input plugin is queried input one of the plugins input channels specified when loading it with vstload position vertical position of plugin to query configfile filename of config file to use description of format see manual NOTE other parameters passed to command supersede corresponding entries in config file type master position 0 current program cell array with all available parameter names

Start of SoundMexPro manual

Contents

Download Pdf Manuals

Related Search

Related Contents