SoundMex Documentation SoundMex Documentation
Contents
1. 16 Date 28 09 04 new free version with limited number of accessible commands introduced see command init init command has additional return value containing licence type information new commands recordthrs and preparerecordthrs for recording n samples after a threshold of m was reached in the record channel Version 1 15 Date 13 09 04 new command setrecordlength introduced SoundMex documentation2. Debugsave exit filetofile getdeviceinfo getlasterror getplaybuffer getrecbuffer getrecorddata getvolume hasclipped help hide init isinitialized ismixing isplaying isrecording memtofile mixfile mixmem mixposition SoundMex documentation Free Basic x x Professional x x x ProfessionalDSP x x x BasicRec x x x ProfessionalRec x x x ProfessionalDSPRec x x x 34 playmem playringbuffer prepareio preparerecord prepareringbuffer record recordprepared sendwaveoutplugin setbutton setplaymode setrecordformat setringbuffersize show startio stopall stopplay stoprec tic x x x x x x version SoundMex documentation 35 10 Common problems FAQ Problem playback or record has dropouts dropouts or deadlocks when using loops with soundmex commands in it system hanging and or matlab crashes when recording when calling getrecorddata errors like File reading error retrying Occur when playing or recording 32bit waves or setting recordformat to 32bit you get an error like specified device cannot play requested format unless your device really should be able to play it 11 Upcoming Features Various realtime DSP Modules e g FIR filtering reverberation pitchshifting delay SoundMex documentation Solution increase the buffersize and number of buffers using the setplaybuffer and set
3. ERE 26 6 1 7 Special Commands ae ene eaea e E RTE E NTE RENSET 28 7 The SoundMex realtime DSP Plugin Pipe sssssssssseeeessssssssseceersssssssecceressssssseecerssssssseeeee 31 8 The SouindMex DSP SD Kiss as 33 9 Peature Matilla sendin Gai a eld Give E 34 10 Common problems FAQ sine rnida neisi ki arriti neniki taei 36 11 Upcoming Feature Sareea in use e IA OAE EEE ia 36 12 VEersion Hist ly ass Benin san Tuner a ET e 37 SoundMex Documentation 4 2 Introduction SoundMex is a powerful tool for 16 and 32bit sound applications in MatLab SoundMex is especially designed for acoustic measurement tasks Psychoacoustics Physical Acoustics Neuro Physiology The software SoundMex 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 SoundMex are synchronous and asynchronous playback and recording real time mixing to asynchronous playback sample accurate sychronization of multiple playback and recording devices devices themselves must support synchronization realtime visualization of levels time signals and spectra ringbuffer mode generate sound data online while device is already playing and feed new data to device record audio while playing and get recorded data directly to MatLab record from multiple devices synchroneously to disk harddisk recording Realtime DSP Plugin Pipe with various DSP plugins for real time signa
4. MB of RAM and a processor speed of 500MHz The more power your computer has the more tracks devices and DSP plugins can be handled simultaneously 4 Installing SoundMex Run SOUNDMEX EXE and follow the installation instructions The following files will be installed on your computer Directory BIN Windows System Directory EXAMPLES PLUGINS DSP SDK MANUAL MANUAL HTML File s SOUNDMEX DLL SOUNDDLL DLL SOUNDDLL INI SOUNDDLL LIC MMTOOLS_C5 BPL VCL50 BPL VCLX50 BPL VCL50 DE TEE50 BPL TEEUI50 BPL various various various SOUNDMEX PDF SOUNDMEX PLUGINS PDF SOUNDMEX HTML related files Descritpion Main program files INI File see below Licence file Copy these files to any directiory in your Matlab search path or add the current directory to it Runtime libraries These files are copied to your Windows system directory Attention copying these files to the Matlab search path or to your current working directory will not be sufficient to run SoundMex Matlab examples and wave files Plugins shipped with SoundMex Documentation examples and sample C Code for the DSP Software Development Kit PDF Help HTML help for access from Matlab Copy HTML and subfolder Soundmex Files to your MatLab ref path see below After installing you should add the BIN directory of your SoundMex installation e g C SoundMex bin to your MatLab path If you want to access the HTML help throug
5. setrecordformat soundmex setrecordformat BitLength Channels SamplingFrequency DevicelD sets the record format for specified record device PARAMETERS BitLength 16 or 32 default on startup is 16 Channels 1 or 2 default on startup is 2 SamplingFrequency Samplingfrequency to record with default on startup iS 44100 DevicelD optional WaveOutDevicelD default is o SoundMex Documentation calculate_while_playing m mark_buttons m modulate m record m Examples record m sync_record m 19 setrecordlength record preparerecord RETURN VALUES outargl1 1 ON SUCCESS O on any error soundmex setrecordlength Length DevicelD record_length m sets the record time for specified record device If setting to o data are recorded to harddisk until stoprecord or stopall is called Any other value will record to memory The last Length samples are stored while recording older values are overwritten Therefore getrecorddata will return the last Length recorded samples PARAMETERS Length Length in samples DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error soundmex record DevicelD record m starts recording of device PARAMETERS DevicelD optional WavelnDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS O on any error soundmex preparerecord DevicelD sync_record m same as record but device is opened only Use this for multiple de
6. CCESS O on any error soundmex hasclipped DevicelD returns the number of clipped samples since the last play command PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarglal 1 ON SUCCESS o on any error outarg 2 number of clipped samples since the last start of the device soundmex setplaymode Mode sets playback mode PARAMETERS Mode one of the follwing values raw fast but not safe vector from MatLab is played directly in soundmex Manipulating that vector during playback will result in an access violation safe data from Matlab will be copied in memory This mode is default RETURN VALUES outargl1 1 ON SUCCESS 0 on any error soundmex getvolume DevicelD SoundMex Documentation record m calculate_while_playing m mark_buttons m rawmode m 18 returns the actual volume factor of the device PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarglal 1 ON SUCCESS o on any error outargl2 actual factor applid to wave data setvolume soundmex setvolume Volume DevicelD sets a volume factor that is applied to the samples before they are sent to the device PARAMETERS Volume All samples will me multiplied with this value in real time Values above 1 or below 1 may cause clipping DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS O on any error 6 1 3 Recording Commands Command Description
7. ERS Size Size in double values default is 81920 DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error setringbuffermode soundmex setringbuffermode Mode DevicelD ringbuffer m sets mode of ringbuffer synchronized_ringbuffers m PARAMETERS Mode string what to do if buffer runs empty error_on_empty an error returns if bufferunderrun occurs stop_on_empty device is stopped if bufferunderrun occurs zero_on_empty zeros are played if bufferunderrun occurs silent playback in this mode the device keeps running you can use putbuffer later on without restarting playback DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error playringbuffer soundmex playringbuffer nBits nSamplingFrequency nChannels DevicelD ringbuffer m starts playback of ringbuffer Some Buffers must be filled before starting if Mode is not set to zero_on_empty PARAMETERS SoundMex Documentation 26 nBits Bitlength for playback 16 or 32 Use 32 for 24 bit devices nSamplingFrequency Samplingfrequency for playback nChannels channels for playback 1 or 2 DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error prepareringbuffer soundmex prepareringbuffer nBits nSamplingFrequency nChannels DevicelD synchronized_ringbuffers m same as playringbuffer but device is opened only Use this for multi
8. SoundMex Documentation Sound Toolkit for MatLab User Manual H rTech Kompetenzzentrum f r H rger te Systemtechnik Copyright H rTech gGmbH Marie Curie Str 2 D 26129 Oldenburg Germany http www hoertech de No warranty subject to alteration 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 other medical devices or weapons systems in which the failure of the Software could lead directly to death personal injury or severe physical or environmental dam
9. age 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 Software except to the extent applicable laws specifically prohibit such restriction LICENSE TRANSFER You may transfer your license and the rights granted in the
10. devices to synchronize them and start all with playprepared DEVICES MUST SUPPORT SYNCHRONIZATION ATTENTION ONLY ASYNC PLAYBACK MODE SUPPORTED PARAMETERS same as in playmem RETURN VALUES outargl1 1 ON SUCCESS o on any error memtofile soundmex memtofile vector nBits nSampFreq outfile DevicelD pumps vector through DSP pipe to file ATTENTION volumes set by command setvolume are NOT applied PARAMETERS SoundMex Documentation 14 vector one or two column vector mono or stereo ATTENTION only values lt 1 within vector otherwise clipping will occur nBits Bitlength for output file 16 or 32 Use 32 for 24 bit devices nSampFreq Samplingfrequency for ouput file ouffile Name for the output file DevicelD optional WaveOutDevicelD default is o Must be set here for plugins RETURN VALUES outargl1 1 ON SUCCESS 0 on any error playprepared soundmex playprepared sync_play m starts playback of all devices already prepared using preparefile or sync_record m preparemem RETURN VALUES outargl1 1 ON SUCCESS 0 on any error isplaying soundmex isplaying DevicelD calculate_while_playing m determines if a device is playing wave data at the moment ringbuffer m PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 1 if specified device is playing o else playposition soundmex playposition DevicelD returns t
11. ed outarg 3 size output buffers setrecbuffer soundmex setrecbuffer NumBuffers BufferSize DevicelD Sets buffer number and size of wavein device USE WITH CARE PARAMETERS NumBuffers Number of buffers used by wavein device SoundMex Documentation Examples device_info m device_info m see setplaybuffer in device_info m 24 BuffersSize Buffersize of buffers used by wavein device DevicelD optional WavelnDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 number of output buffers after setting outarg 3 size output buffers after setting getrecbuffer soundmex getrecbuffer DevicelD see getplaybuffer returns information about buffer number and size of wavein device in the device_info m second and the size of the buffers in the third return value PARAMETERS DevicelD optional WavelnDevicelD defaultis o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 number of output buffers used outarg 3 size output buffers getdeviceinfo soundmex getdeviceinfo device_info m returns information on all installed WaveOut and Waveln devices RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outarg 2 string based information on all devices SoundMex Documentation 25 in 6 1 6 Ringbuffer Commands Command Description Examples setringbuffersize soundmex setringbuffersize Size DevicelD ringbuffer m sets size of ringbuffer synchronized_ringbuffers m PARAMET
12. g RETURN VALUES outargl1 1 ON SUCCESS 0 on any error prepareio soundmex prepareio Waveout Deviceld Wavein Deviceld same as Startio but devices are opened only Use this for multiple devices to synchronize them and start all with startpreparedio DEVICES MUST SUPPORT SYNCHRONIZATION PARAMETERS same as in Startio RETURN VALUES outargl1 1 ON SUCCESS 0 on any error startpreparedio soundmex startpreparedio Waveout Deviceld Wavein Deviceld starts io of all devices already prepared with prepareio RETURN VALUES outargl1 1 ON SUCCESS 0 on any error SoundMex Documentation 23 6 1 5 Device Commands Command Description setplaybuffer soundmex setplaybuffer NumBuffers BufferSize DevicelD Sets buffer number and size of waveout device USE WITH CARE PARAMETERS NumBuffers Number of buffers used by waveout device BuffersSize Buffersize of buffers used by waveout device DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 number of output buffers after setting outarg 3 size output buffers after setting getplaybuffer soundmex getplaybuffer DevicelD returns information about buffer number and size of waveout device in the second and the size of the buffers in the third return value PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarglal 1 ON SUCCESS o on any error outargl2 number of output buffers us
13. h for output Specify this value if ouput format should be different from file format 16 or 32 only Use 32 for 24 bit devices ATTENTION if you want to use the nBits flag you must specify the DevicelD too not optional any longer ATTENTION What kind of 32bit waves you can use depends on the capabilities of your device if you use wrong formats the output may overdrive To be sure use 32bit Integer wave files Goody if you select async and LoopCount o you can specify RETURN VALUES an extra parameter random if so you must give the DevicelD too if you specify random as last parameter the playback start position within the file is chosen randomly SoundMex Documentation 12 outarglal 1 ON SUCCESS o on any error preparefile soundmex preparefile filename Mode LoopCount DevicelD nBits random same as playfile but device is opened only Use this for multiple devices to synchronize them and start all with playprepared DEVICES MUST SUPPORT SYNCHRONIZATION ATTENTION ONLY ASYNC PLAYBACK MODE SUPPORTED PARAMETERS same as in playfile RETURN VALUES outargl1 1 ON SUCCESS 0 on any error filetofile soundmex filetofile filename outfile DevicelD nBits pumps file through DSP pipe to file ATTENTION volumes set by command setvolume are NOT applied PARAMETERS filename the filename Must be a valid Windows PCM Wavefile outfile name of the output file DevicelD opt
14. h the matlab command doc soundmex please copy the file SOUNDMEX HTML and the subfolder SOUNDMEX FILES from the Manual HTML subdirectory e g C SoundMex manual to the directory lt matlab path gt help techdoc ref e g C MATLAB6p5 help techdoc ref SoundMex Documentation You can set the temporary path of SoundMex path were recorded data will be stored by modifying the path variable in the file SOUNDDLL INI or in your user defined INI File see command init e g System TempPath c temp Caution Never run SoundMex from network drives or set its temporary path to a network drive 5 Uninstalling SoundMex An uninstaller is shipped with SoundMex Select Uninstall SoundMex from the start menu or run the uninstaller from the control panel The copy protection driver will not be removed by this uninstaller to avoid problems with other dongles If you want to remove the dongle driver manually please perform the following steps If a version of SoundMex v1 18 or below or SoundMex2 2 08 or below was installed on your system please call the command hinstall r from the command prompt in the HASP subdirectory of your SoundMex installation e g c soundmex hasp or if this directory does not exist form your system directory e g c winnt system32 After the command has completed the file HINSTALL EXE can be deleted For removing the dongle driver for SoundMey v1 19 or above or SoundMex2 v2 09 or abo
15. he actual playing position in samples PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES SoundMex Documentation 15 outargl1 1 on success o on any error outargl 2 actual playing position in samples mixfile soundmex mixfile filename Mode DevicelD mix file to already playing device PARAMETERS filename the filename Must be a valid Windows PCM Wavefile Mode add or multiply DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error mixmem soundmex mixmem vector Mode DevicelD mixsignal from meory buffer to already playing device PARAMETERS vector one or two column vector mono or stereo ATTENTION only values lt 1 otherwise clipping will occur ATTENTION if playing in raw mode see setmode never touch this vector during playback Mode add or multiply DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error ismixing soundmex ismixing DevicelD returns 1 if requested Device is mixing or o else ATTENTION ismixing will return 1 if a mix is pending data are mixed actually but the mixed buffers have not arrived at the device yet and so the mixed data are not audible yet Before the mixed output is audible mixposition will return negative values SoundMex Documentation mark_buttons m modulate m see mark_buttons m for mixfile mark_buttons
16. he devices Is called automatically when unloading soundmex Use this command for resetting all devices and buffers RETURN VALUES outargl1 1 ON SUCCESS O on any error soundmex show OUTDEVICES INDEVICES Shows window with devices and data visualization PARAMETERS OUTDEVICES row vector with device ID s of playback devices to show INDEVICES row vector with device ID s of recording devices to show RETURN VALUES outargl1 1 ON SUCCESS o on any error soundmex hide Hides window with devices RETURN VALUES outargl1 1 ON SUCCESS 0 on any error soundmex getlasterror param shows last error string RETURN VALUES SoundMex Documentation device_info m mark_buttons m sync_play m error_handling m 10 outargl 1 ON success o on any error outargl2 last error message as string SoundMex Documentation 11 6 1 2 Playback Commands Command Description Examples playfile soundmex playfile filename Mode LoopCount DevicelD nBits random calculate_while_playing m plays sound from file mark_buttons m PARAMETERS modulate m filename the filename Must be a valid Windows PCM Wavefile record m Mode string sync or async async starts playing file and returns immediately sync plays file and returns after playback is complete LoopCount number of times file should be played o does infinite loop in async mode only DevicelD optional WaveOutDevicelD default is o nBits optional bitlengt
17. ional WaveOutDevicelD default is o Must be set here for plugins nBits optional bitlength for output Specify this value if ouput format should be different from file format 16 or 32 only Use 32 for 24 bit devices ATTENTION if you want to use the nBits flag you must specify the DevicelD too not optional any longer RETURN VALUES outarglal O on success o on any error playmem soundmex playmem vector nBits nSampFreq Mode LoopCount DevicelD plays sound from memory PARAMETERS SoundMex Documentation see sync_play m for preparemem sync_record m sync_play m 13 vector one or two column vector mono or stereo ATTENTION only values lt 1 within vector otherwise clipping will occur ATTENTION if playing in raw mode see setmode never touch this vector during playback nBits Bitlength for playback 16 or 32 Use 32 for 24 bit devices nSampFreq Samplingfrequency for playback Mode string sync or async async starts playback and returns immediately sync starts playback and returns after playback is complete LoopCount number of times file vector should be played o does infinite loop in async mode only DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS O on any error preparemem soundmex preparemem vector nBits nSamFreq Mode LoopCount DevicelD sync_play m same as playmem but device is opened only Use this for multiple
18. l processing DSP Plugin SDK Software Development Kit for user defined realtime plugins for blockwise wave and spectrum manipulation o script based plugins user defined MatLab commands are called from the DSP pipe Manipulated data are written back to the pipe o Simple API for development of fast binary user plugins in any programming language direct I O recorded data can be directly or after processing the data with DSP Plugins mapped to a waveout for playback special command for highlighting buttons on a MatLab window sample accurate hightlighting at desired playback positions for signal synchronous user feedback A free version of SoundMex is available with the follwing restrictions only a small subset of commands is available see feature matrix below only one device can be used at the same time The first call to a command with a device parameter selects the device to use A device with another ID can be used after the next call of soundmex init A demo version of SoundMex is available for free The demo version has the following restrictions a demo message is shown on init and after every five minutes sound input and output is stopped every five minutes SoundMex Documentation 5 additional sound the spoken words soundmex demo is added to all playbacks and recordings at random times 3 System Requirements SoundMex runs on MatLab 5 3 and above on Windows 9x and above The computer should have at least 128
19. 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 transfered to the third party and d the transfer includes the current version and all prior versions of the Software SoundMex 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 fails 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 gG
20. m modulate m record m 16 PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarglal 1 ON SUCCESS o on any error outargl2 1 if specified device is playing o else mixposition soundmex mixposition DevicelD record m returns the actual mixing position ATTENTION ismixing will return 1 if a mix is pending data are mixed actually but the mixed buffers have not arrived at the device yet and so the mixed data are not audible yet Before the mixed output is audible mixposition will return negative values PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 actual mixing position in samples stopplay soundmex stopplay DevicelD calculate_while_playing m stops playback of device PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error stopplayall soundmex stopplayall calculate_while_playing m stops playback of all devices RETURN VALUES outargl1 1 ON SUCCESS 0 on any error stopmix soundmex stopmix DevicelD SoundMex Documentation 17 stopall hasclipped setplaymode getvolume stops mixing if mixing is active PARAMETERS DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarglal 1 ON SUCCESS o on any error soundmex stopall stops playback and recording of all devices RETURN VALUES outargl1 1 ON SU
21. mbH 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 SoundMex Documentation 3 1 Contents Elcenseragteementan a RA RS BA AAA 2 T CONTENTS RR 4 2 Introduction eeesccsesessessssssnnsnssnennensnnnnnnnnsnnnnnnnnnnnnnensnnnnnsnnsnnnnssssnnnnssssensnnssssnnnsssssenssssssennnne 5 3 gt System Requlrementsan sseensseslenssslnntensstnnsi ini ERBEN Inne 6 4 lristalliig SOUNAUMEXsssseciecsescccscssavccacesssceacuonvcca ceasesenceebesed seas epedeved esedesebusededetusedeseawsossoenvens 6 5 Uninstalling SOU AMEX 20st ssisestessyes ches socedhes EO EE 7 6 Command Description session Bienen aeeasesisesseesseseadessseaseees 8 6 1 1 General Commands 4 2222 ia EG S tases elias Swed Acie 9 6 12 Playback Command S penina na a eens 12 6 1 3 Recording Command ate and asc 19 6 1 4 Input Output CommandsS sssseesssseessssseesssseeessseeessseeessseeesssscesssseeessseeessseeessseeeos 23 64 5 AAA eaaeo A ASe EEA ESAR Eo Esay a eins eyai 24 6 1 6 Ringbuffer Commands arenen n a a a E
22. mentation 21 stoprec stoprecall saverecord getrecorddata RETURN VALUES outarg 1 ON SUCCESS o on any error outargl2 1 if specified device is recording o else soundmex stoprec DevicelD stops recording of device PARAMETERS DevicelD optional WavelnDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS O on any error soundmex stoprecall stops recording of all devices RETURN VALUES outargl1 1 ON SUCCESS 0 on any error soundmex saverecord filename DevicelD saves recorded data from Device to file Windows PCM Wavfile 16 or 32bit integer PARAMETERS filename filename to save wave to DevicelD optional WavelnDevicelD default is o RETURN VALUES outargl1 1 on success o on any error soundmex getrecorddata Deviceld record m returns recorded wave data from device as row vector sync_record m PARAMETERS DevicelD optional WavelnDevicelD defaultis o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outarg 2 row vector SoundMex Documentation 22 6 1 4 Input Output Commands Command Description Examples startio soundmex startio Waveout Deviceld Wavein Deviceld start_io m starts recording and mapping recorded sound directly to output Use setrecordformat to set the desired record format before using startio Playback format will be identical to record format PARAMETERS Waveout Deviceld WaveOutDevicelD for playback Wavein Deviceld WavelnDevicelD for recordin
23. nd do not consume much processor power except for the Visualisation plugin The plugins are p ugged together by the chain in a manner that the output data of the first plugin are the input data for the second plugin and so on Activating a plugin chain A plugin chain for one or more devices is activated by adding a line to the SoundMex INI File either the default file or the user definded file see command init WaveOutPlugins 0 plugins pluginO ini 1 plugins pluginl ini WavelnPlugins O plugins plugin7 ini l plugins plugin8 ini The sections WaveOutPlugins and Wave nPlugins respectively denote if the chain is to be plugged into the signal path of a playback or recording device The name of the value is the corresponding DevicelD of the recording or playback device The value right hand of the specifies another INI File describing a single plugin chain See below Configuring a plugin chain Every plugin chains is configured with a INI File Such a chain INI File contains an optional section G oba Data and one section for each plugin to be used GlobalData MyData 100 MyData2 200 0 FileName plugins visualize dll LogView 1 1 SoundMex documentation 31 FileName plugins olaeq dll EQFile plugins conv_1024 cnv OLAFFTLength 1024 OLAWindowLength 800 2 FileName plugins visualize dll LogView 1 The GlobalData section contains fields that are available to all plugins du
24. ned above was activated for waveout device No o i e the file plugino ini from Activating a plugin chain is used For a list of recognized commands of the generic plugins please refer to the SoundMex DSP Plugins documentation 6 Communication with the plugin chain and updating global data The plugin chain itself can receive commands using 1 as plugin index in the sendwaveoutplugin and sendwaveinplugin command The following commands are supported Command Description show shows the specified plugin chain The command takes three optional parameters separated by spaces first is the window position in pixels from the left second is the window position in pixels from the top and complete rest will be set as window caption for example soundmex sendwaveoutplugin show 100 100 Hello World 1 Attention If you want to use the second or third parameter all prior arguments must be given as well Calling show without parameters will show the plugin chain either at the top left corner of the screen or if the SoundMex main window is visible to the SoundMex documentation 32 right ofthe main window hide hides the plugin chain soundmex sendwaveoutplugin hide 1 notify with notify you can update or add global data All plugins except external plugins see SDK will re read settings that they have read on initialization if possible You can specify an arbitrary number of arguments in the form name val
25. ple devices to synchronize them and start all with playprepared DEVICES MUST SUPPORT SYNCHRONIZATION PARAMETERS same as in playbuffer RETURN VALUES outargl1 1 ON SUCCESS 0 on any error putringbuffer soundmex putringbuffer vector DevicelD ringbuffer m puts data to the ringbuffer synchronized_ringbuffers m PARAMETERS vector one or two row vector mono or stereo ATTENTION Here the format is different to playmem samples in rows _not_ in columns ATTENTION only values lt 1 otherwise clipping will occur DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS O on any error outarg 2 1 if buffer data were accepted o if ringbuffer is busy filled completely In that case try it again later SoundMex Documentation 27 6 1 7 Special Commands Command tic toc setbutton Description Examples soundmex tic tictoc m resets SoundMex internal tic toc counter RETURN VALUES outargl1 1 ON SUCCESS 0 on any error soundmex toc tictoc m returns elapsed time since last tic command in milliseconds RETURN VALUES outarglal 1 ON SUCCESS o on any error outargl2 elapsed time since last tic command in milliseconds soundmex setbutton windowcaption buttoncaption mode startpos duration DevicelD mark_buttons m use soundmex to highlight buttons in a Matlab Window PARAMETERS windowcaption Caption ofthe window with the buttons substring sufficient buttoncaption Cap
26. recordbuffer commands put asmall pause anywhere in the loop e g pause 0 0001 otherwise the windows message loop is not processed accurately be sure that you do not run SoundMex from a network drive and that the temporaray path of SoundMex does not point to a network drive see Installation above be sure that you do not run SoundMex from a network drive and thatthe temporaray path of SoundMex does not point to a network drive see Installation above enter the control panel and select No Sounds in your Sounds and Multimedia settings otherwise some Windows messagebox may play ding in 16 bit mode and your soundcard is blocked for higher resolutions at that time 36 12 Version History Version history starting with version 1 13 Version 1 21 Date 08 06 05 Initialization timout increased to 10 seconds for slow plugins Filter reading for equalizer plugin rewritten for higher efficiency Version 1 20 Date 26 05 05 Dongle driver problem on some XP machines fixed Version 1 18 Date 26 10 04 getdeviceinfo now supported by free version documentation changed for 24 bit devices and bitlength parameter new command playposition to retrieve actual position within playback Version 1 17 Date 26 10 04 bugfix for random startposition recordthrs rewritten now the the exact numer of samples starting with the first sample with the threshold value are saved Version 1
27. ring initialization i e all plugins can read these values All other sections decribe one plugin each The names of the section must be ascending integer values not subsequent but ascending The only required field is FileName which holds the name of the DLL that will be loaded by the plugin chain All other parameters are plugin specific Every plugin can read these values during initialization Plugins that require further parameters will fail to initialize ifa value is missing So the above example describes a plugin chain containing three plugins for a description of those generic plugins please refer to the SoundMex DSP Plugins documentation atthe first position the data are visualized spectrum spectrogram the second plugin is an overlapped add equalizer spectral manipulation the third is again a visualization to see changes done by the equalizer The data will flow from top to bottom through these plugins 5 Communication with plugins After initializing SoundMex you can use the sendwaveoutplugin and sendwaveinplugin command to communicate with a plugin String commands can be sent to a single plugin but the plugin itself must recognize the command In the example above you can activate and deactivate the equalizer on the fly usingthe command soundmex sendwaveoutplugin active 1 1 0 Sactivation soundmex sendwaveoutplugin active 0 1 0 Sdeactivation assuming the plugin chain defi
28. s Command Description Examples help soundmex help command shows help for specified command use soundmex help to see a list of all commands use soundmex help all to see help on all commands PARAMETERS command name of the command or all RETURN VALUES outargl1 1 ON SUCCESS 0 on any error version soundmex version shows version information about SOUNDMEX DLL and SOUNDDLL DLL init soundmex init IniFile InitMode all examples initializes the devices Must be called before any other action except checklicence m isinitialized and getdeviceinfo PARAMETERS IniFile optional filename for the inifile to use especially useful when usingDSP Plugins InitMode optional parameter with the follwing values free switches licence mode to free with limited features force if soundmex was already initialized the internal exit command is called followed by init forcefree if soundmex was already initialized the internal exit command is called followed by soundmex init free SoundMex Documentation 9 isinitialized exit show hide getlasterror RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 string containing licence type information soundmex isinitialized use this command to determine if soundmex is already initialized RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 1 if initialized o else soundmex exit resets t
29. show 10 100 My Window 1 0 Pluginid position of plugin within chain first plugin has ID o PluginCain itself has ID 1 DevicelD optional WaveOutDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error outargl2 string based return value from plugin depends on command See also the chapter The SoundMex realtime DSP Plugin Pipe sendwaveinplugin same as sendwavoutplugin but for a plugin chain defined for a Waveln Device nn SoundMex Documentation 29 SoundMex Documentation 30 7 The SoundMex realtime DSP Plugin Pipe SoundMex contains a built in realtime DSP Plugin Pipe It is avaliable only with the DSP and DSP SDK licences General descriptions 1 Plugins SoundMex DSP Plugins are binary modules DLL s that can manipulate sound data sent to or received from a wave device on the fly Several plugins can be p ugged together using a plugin manager a so called plugin chain Various and a growing number of generic plugins is shipped with SoundMex user defined plugins can be developed using the SoundMex DSP SDK Software Development Kit see below Plugin chains Every device recording or playback device can define a so called plugin chain A plugin cha nis a container for a variable number of SoundMex DSP Plugins The number of plugins is limited only by the speed of your computer and how expensive calculations are within the single plugins The generic plugins are highly optimized a
30. t by the user Both plugin types can be realized in two different ways script based MatLab plugins a user defined MatLab command script or mex is called on runtime within the DSP Pipe Wave data are passed blockwise to the command Data can easily be manipulated in the script and passed back to the DSP Pipe as output argument This kind of plugin is extremly easy to use but is limited in the performance binary plugins high performance plugins can be realized in any programming language that can build Windows Dynamic Link Libraries DLL These libraries can be written in any programing language that can build Dynamic Link Libraries DLL Implementation can be easily done without any knowledge of windows multimedia sound devices or other special programing skills Implementing one function with only some ANSI C floating SoundMex documentation 33 point calculations the manipulation of the signal is sufficient for many applications A simple API reference and some examples are shipped with the SDK For a complete documentation please refer to the SoundMex DSP SDK documentation that is available on demand 9 Feature Matrix SoundMex is shipped with different licences with different registration fees The feature matrix below gives an overview on the different licences The SDK licences are identical to ProfessionalDSP licences with the additional feature that they can load external user defined plugins
31. tion of the button exact string mode mix or org Calculate positions relative to original played loop in background or relative to mixfile mixmem startpos Position in samples when button should be highlighted duration After startpos duration the button returns to normal state DevicelD optional WaveOutDevicelD default is o CAUTION if you want to use the org parameter you _must_ call setbutton before starting the playback if you use mix you may call it after starting the playback but before start mixing RETURN VALUES outargl1 1 ON SUCCESS 0 on any error SoundMex Documentation 28 debugsave soundmex debugsave filename DevicelD modulate m saves wave output to wave file PARAMETERS filename filename Passing an empty string as filename disables debugsave DevicelD optional WaveOutDevicelD default is o RETURN VALUES outarg i 1 ON SUCCESS o on any error sendwaveoutplugin soundmex sendwaveoutplugin command Pluginld Deviceld plugin m sends a command to a plugin PARAMETERS command command to be sent Plugin or PluginChain itself must recognize command PluginChain itself only knows commands show and hide If passing show you can pass additonal parameters in the string separated by blanks first parameter left position of window in pixels second parameter top position of window in pixels the complete rest caption of window for example soundmex sendwaveoutplugin
32. ue separated by space e g soundmex sendwaveoutplugin notify MyData 50 MyData2 100 1 Attention the plugin itself must support notify actions Please test your application seriously You can show hide a plugin chain by clicking the small button to the right of the levelmeter on the main SoundMex window after calling soundmex show too For an example see plugin m in the examples directory For a description of the generic SoundMex DSP Plugins and their parameters please refer to the SoundMex DSP Plugins documentation 8 The SoundMex DSP SDK The SoundMex DSP SDK is a software development for building user defined realtime plugins for the SoundMex DSP Plugin Pipe It provides two different types of user defined SoundMex DSP Plugins plugins for manipulations in the time domain the plugin gets blockwise access to the wave data as normalized floating point values and can manipulate each sample directly before it is sent to the device or a subsequent plugin plugins for manipulations in the frequency domain the plugin gets access to the complex FFT spectrum of signal blocks before they are reconstructed and sent to the device ora subsequent plugin Data segementation before the FFT and data reconstruction after the IFFT is done by overlapped add procedure FFT length as well as window length zero padding if window length lt FFT length and window feed half quarter or eighth for the overlapped add can be se
33. ve please call the command haspdinst r from the command prompt in the HASP subdirectory of your SoundMex installation e g c soundmex2 hasp After the command has completed the file HASPDINST EXE can be deleted SoundMex Documentation 7 6 Command Description All SoundMex commands have a similar syntax outargl outarg2 soundmex command argl arg2 All commands return one output argument at least This return value outargl1 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 soundmex commands e g Success soundmex init if Success error Cannot initialize soundmex end Commands with additional return values write these to outarg 2 outarg n e g Success ClipCount soundmex hasclipped if Success error Error in command hasclipped end disp playback has clipped num2str ClipCount times Success NumBuf BufSiz soundmex getplaybuffer if Success error error in command getplaybuffer end disp playback device has num2str NumBuf y buffers of d num2str BufSiz bytes size The table below shows a list of all available commands sorted by functionality In the column Examples you can find a list of example scripts that are related to the specified command SoundMex Documentation 8 6 1 1 General Command
34. vices to synchronize them and start all with recordprepared DEVICES MUST SUPPORT SYNCHRONIZATION PARAMETERS DevicelD optional WavelnDevicelD default is o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error SoundMex Documentation 20 recordthrs soundmex recordthrs DevicelD thrs_record m starts recording of device after the Threshold was exceeded within the recording device once PARAMETERS Threshold Number between o and 1 o starts recording immediately NumSamples Number of samples to record DevicelD optional WavelnDevicelD defaultis o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error preparerecordthrs soundmex preparerecordthrs Threshold NumSamples DevicelD same as recordthrs but device is opened only Use this for multiple devices to synchronize them and start all with recordprepared DEVICES MUST SUPPORT SYNCHRONIZATION PARAMETERS Threshold Number between o and 1 o starts recording immediately NumSamples Number of samples to record DevicelD optional WavelnDevicelD defaultis o RETURN VALUES outargl1 1 ON SUCCESS 0 on any error recordprepared soundmex recordprepared sync_record m starts recording of all devices already prepared using preparerecord RETURN VALUES outargl1 1 ON SUCCESS 0 on any error isrecording soundmex isrecording DevicelD determines if a device is recording wave data at the moment PARAMETERS DevicelD optional WavelnDevicelD default is o SoundMex Docu
Download Pdf Manuals
Related Search