Faust2api: a Comprehensive API Generator for Android and Ios
Total Page:16
File Type:pdf, Size:1020Kb
faust2api: a Comprehensive API Generator for Android and iOS Romain Michon, Julius Smith, St´ephaneLetz, Yann Orlarey Chris Chafe GRAME CCRMA Centre National de Cr´eationMusicale Stanford University 11 Cours de Verdun (Gensoul) Stanford, CA 94305-8180 69002, Lyon USA France frmichon,jos,[email protected] fletz,[email protected] Abstract use objects written in common computer music 6 We introduce faust2api, a tool to generate cus- languages such as PureData: libpd [Brinkmann tom DSP engines for Android and iOS using the et al., 2011] and Csound:7 Mobile Csound Plat- Faust programming language. Faust DSP objects form (MCP) [Lazzarini et al., 2012] on mobile can easily be turned into MIDI-controllable poly- platforms. phonic synthesizers or audio effects with built-in sen- Similarly, we introduced faust2android sors support, etc. The various elements of the DSP in a previous publication [Michon, 2013]: a engine can be accessed through a high-level API, tool allowing to turn Faust8 [Orlarey et al., made uniform across platforms and languages. This paper provides technical details on the im- 2009] code into a fully operational Android plementation of this system as well as an evaluation application. faust2android is based on of its various features. faust2api [Michon et al., 2015]. It al- lows to turn a Faust program into a cross- Keywords platform API usable on Android and iOS to Faust, iOS, Android, Mobile Instruments carry out various kinds of real-time audio pro- cessing tasks. 1 Introduction In this paper, we present a completely re- Mobile devices (smart-phones, tablets, etc.) designed version of faust2api offering the have been used as musical instruments for the same features on Android and iOS: past ten years, both in the industry (e.g., • polyphony and MIDI support, GarageBand1 for iPad, Smule's apps,2 mo- Forte's GeoShred,3 etc.), and in the academic • audio effects chains, community ([Tanaka, 2004], [Geiger, 2006], • built-in sensors support, [Gaye et al., 2006], [Essl and Rohs, 2009] and • low latency audio, [Wang, 2014]). Implementing real-time Digital Signal Pro- • etc. cessing (DSP) engines from scratch on mobile First, we'll give an overview of how platforms can be hard using standard audio faust2api works. Then, technical details on APIs provided with common operating systems the implementation of this system will be pro- (we'll only cover iOS and Android here). In- vided. Finally, we'll evaluate it and present fu- deed, CoreAudio on iOS and OpenSL ES on ture directions for this project. Android are relatively low-level APIs offering customization possibilities not needed by most 2 Overview audio app developers. Fortunately, there ex- 2.1 Basics ist several third party cross-platform APIs to work with real-time audio on mobile devices at a At its highest level, faust2api is a command higher level (e.g., SuperPowered,4 JUCE,5 etc.). line program taking a Faust code as its main Additionally, several open-source tools allow to argument and generating a package containing a series of files implementing the DSP engine. 1http://www.apple.com/ios/garageband. All Various flags can be used to customize the API. the URLs in this paper were verified on 01/26/17. The only required flag is the target platform: 2https://www.smule.com 3http://www.moforte.com/geoshredapp 6https://puredata.info 4http://superpowered.com 7http://www.csounds.com 5https://www.juce.com 8http://faust.grame.fr faust2api -ios myCode.dsp 2.2 MIDI Support will generate a DSP engine for iOS and MIDI support can be easily added to a faust2api -android myCode.dsp DspFaust object simply by providing the -midi flag when calling faust2api. MIDI will generate a DSP engine for Android. support works the same way on Android and The content of each package is quite different iOS: all MIDI devices connected to the mobile between these two platforms (see x3), but the device before the app is launched can control the format of the API itself remains very similar Faust object, and any new device connected (see Figure 1 at page 4). The iOS DSP engines while the app is running will also be able to faust2api generated with consist of a large control it. C++ object (DspFaust) accessible through a Standard Faust MIDI meta-data9 can be separate header file. This object can be con- used to assign MIDI CCs to specific parame- C++ veniently instantiated and used in any or ters. For example, the freq parameter of the Objective-C code in an app project. A typi- previous code could be controlled by MIDI CC DspFaust cal \life cycle" for a object can be 52 simply by writing DspFaust *dspFaust = new DspFaust(SR, blockSize); dspFaust->start(); f = nentry("freq[midi: ctrl dspFaust->stop(); delete dspFaust; 52]",440,50,1000,0.01); start() launches the computation of the 2.3 Polyphony audio blocks and stop() stops (pauses) the objects can be conveniently turned into computation. These two methods can be re- Faust polyphonic synthesizers simply by specifying peated as many times as needed. The construc- the maximum number of voices of polyphony tor allows to specify the sampling rate and the when calling faust2api using the -nvoices block size, and is used to instantiate the au- flag. In practice, only active voices are allocated dio engine. While the configuration of the au- and computed, so this number is just used as a dio engine is very limited at the API level (only safeguard. these two parameters can be configured through As used for many years by the various it), lots of flexibility is given to the program- tools for making Faust synthesizers, such as mer within the Faust code. For example, if faust2pd, compatibility with the -nvoices the Faust object doesn't have any input, then option requires the freq, gain and gate pa- no audio input will be instantiated in the audio rameters to be defined. faust2api automati- engine, etc. cally takes care of converting MIDI note num- The value of the different parameters of a bers to frequency values in Hz for freq, MIDI Faust object can be easily modified once the velocity to linear amplitude-gain for gain, and DspFaust object is created and is running. note-on (1) and note-off (0) for gate: For example, the freq parameter of the sim- ple Faust code f = nentry("freq",440,50,1000,0.01); g = nentry("gain",1,0,1,0.01); f = nentry("freq",440,50,1000,0.01); t = button("gate"); process = osc(f)*g* process = osc(f); t; can be modified simply by calling Here, t could be used to trigger an envelope dspFaust->setParamValue("freq",440); generator, for example. In such a case, the voice Faust user-interface elements (nentry here) would stop being computed only after t is set are ignored by faust2api and simply used as to 0 and the tail-off amplitude becomes smaller a way to declare parameters controllable in the than -60dB (configurable using macros in the API. API packages generated by faust2api application code). also contain a markdown documentation pro- A wide range of methods is accessible to work viding information on how to use the API as with voices. A \typical" life cycle for a MIDI well a list of all the parameters controllable with note can be setParamValue(). long voiceAddress = dspFaust->keyOn( The structure of the DSP engine package note,velocity); is quite different for Android since it contains dspFaust->setVoiceParamValue("param", both C++ and JAVA files (see x3). Otherwise, voiceAddress,paramValue); the same steps can be used to work with the 9http://faust.grame.fr/images/ DspFaust object. faust-quick-reference.pdf dspFaust->keyOff(note); its custom DSP engines. [Letz et al., 2017] For setVoiceParamValue() can be used to example, turning a monophonic Faust synthe- change the value of a parameter for a specific sizer into a polyphonic one can be done in a voice. simple generic way. Both on Android and iOS, faust2api C++ Alternatively, voices can be allocated without generates a large file imple- specifying a note number and a velocity: menting all the features used by the high level API. On iOS, this API is accessed through a long voiceAddress = dspFaust->newVoice C++ header file that can be conveniently in- (); dspFaust->setVoiceParamValue("param", cluded in any C++ or Objective-C code. On voiceAddress,paramValue); Android, a JAVA interface allows to interact dspFaust->deleteVoice(voiceAddress); with the native (C++) block. The DSP C++ For example, this can be very convenient to code is the same for all platforms (see Figure 2 associate voices to specific fingers on a touch- at page 5) and is wrapped into an object imple- screen. menting the polyphonic synthesizer followed by When MIDI support is enabled in the effects chain (assuming that the -mvoices faust2api, MIDI events will automati- and -poly2 options were used during compila- cally interact with voices. Thus, if a MIDI tion). keyboard is connected to the mobile device, In this section, we provide more information it will be able to control the Faust object on the architecture of DSP engines generated without additional configuration steps. by faust2api for Android and iOS. 2.4 Adding Audio Effects 3.1 iOS In most cases, effects don't need to be re- The global architecture of API packages gen- implemented for each voice of polyphony and erated by faust2api is relatively simple on can be placed at the end of the DSP chain. iOS since C++ code can be used directly in faust2api allows to provide a Faust object Objective-C (which is one of the two lan- implementing the effects chain to be connected guages used to make iOS applications along to the output of the polyphonic synthesizer.