E M B E D D E D A U D I O S Y N T H E S I S
Sonic Network, Inc.
Embedded Audio Synthesis (EAS)
EAS API Reference
(Version 3.6)
Copyright 2008 Sonic Network, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Sonic Network, Inc.
561 Windsor Street
Suite A402
Somerville, MA 02143
USA
Table of Contents
1 Introduction ............................................................................................................................ 5
1.1 Abstract ........................................................................................................................... 5
1.2 Intended Audience ........................................................................................................... 5
1.3 Abbreviations ................................................................................................................... 5
1.4 Revision History ............................................................................................................... 5
1.5 References and related documents ................................................................................. 5
2 EAS Library ............................................................................................................................ 6
2.1 Overview ......................................................................................................................... 6
2.3 Upgrading From Previous Versions ................................................................................. 7
3 Theory of Operation ............................................................................................................... 7
3.1 General API usage .......................................................................................................... 7
3.2 Host Wrapper .................................................................................................................. 7
3.3 Memory Model ................................................................................................................. 8
3.4 Streams ........................................................................................................................... 8
3.5 Polyphony ........................................................................................................................ 8
3.6 Priority ............................................................................................................................. 9
4 Public Interface ...................................................................................................................... 9
4.1 Main Library Functions .................................................................................................... 9
4.1.1 EAS_Init .................................................................................................................... 9
4.1.2 EAS_Render ............................................................................................................. 9
4.1.3 EAS_Shutdown ......................................................................................................... 9
4.1.4 EAS_Config .............................................................................................................. 9
4.1.5 EAS_SetMaxLoad ................................................................................................... 10
4.1.6 EAS_SetParameter ................................................................................................. 11
4.1.7 EAS_GetParameter ................................................................................................ 11
4.2 Stream Functions ........................................................................................................... 11
4.2.1 EAS_OpenFile ........................................................................................................ 11
4.2.2 EAS_Prepare .......................................................................................................... 12
4.2.3 EAS_CloseFIle ........................................................................................................ 12
4.2.4 EAS_State .............................................................................................................. 12
4.2.5 EAS_Locate ............................................................................................................ 12
4.2.6 EAS_GetLocation ................................................................................................... 12
4.2.7 EAS_Pause ............................................................................................................. 13
4.2.8 EAS_Resume ......................................................................................................... 13
4.2.9 EAS_SetPriority ...................................................................................................... 13
4.2.10 EAS_GetPriority .................................................................................................... 13
4.2.11 EAS_SetRepeat .................................................................................................... 13
4.2.12 EAS_SetPlaybackRate ......................................................................................... 13
4.2.13 EAS_SetTransposition .......................................................................................... 14
4.3 MIDI Stream Functions .................................................................................................. 14
4.3.1 EAS_OpenMIDIStream ........................................................................................... 14
4.3.2 EAS_WriteMIDIStream ........................................................................................... 14
4.3.3 EAS_CloseMIDIStream .......................................................................................... 15
4.4 Volume Control .............................................................................................................. 15
4.4.1 EAS_SetVolume ..................................................................................................... 15
4.4.2 EAS_GetVolume ..................................................................................................... 15
4.5 Polyphony Control ......................................................................................................... 15
4.5.1 EAS_SetSynthPolyphony ....................................................................................... 15
4.5.2 EAS_GetSynthPolyphony ....................................................................................... 16
4.5.3 EAS_SetPolyphony ................................................................................................. 16
4.5.4 EAS_I32 EAS_GetPolyphony (EAS_DATA_HANDLE pEASData, EAS_HANDLE
streamHandle) ................................................................................................................. 16
4.6 Metadata ....................................................................................................................... 16
4.6.1 RegisterMetaDataCallback ..................................................................................... 16
Copyright 2008 SONIC NETWORK, INC. EAS Version 3.6 Page 2/34
4.6.2 EAS_ParseMetaData .............................................................................................. 17
4.6.3 EAS_GetFileType ................................................................................................... 17
4.7 Miscellaneous ................................................................................................................ 17
4.7.1 EAS_SetHeaderSearchFlag ................................................................................... 17
4.7.2 EAS_SetPlayMode ................................................................................................. 17
5 Configuration Module (CM) .................................................................................................. 18
5.1 CM Preprocessor Defines ............................................................................................. 18
5.1.1 _STATIC_MEMORY ................................................................................................ 18
5.2 Parser Options ............................................................................................................... 18
5.2.1 _CMX_PARSER ..................................................................................................... 18
5.2.2 _IMELODY_PARSER ............................................................................................. 18
5.2.3 _MFI_PARSER ....................................................................................................... 18
5.2.4 _OTA_PARSER ...................................................................................................... 18
5.2.5 _RTTTL_PARSER .................................................................................................. 19
5.2.6 _SMAF_PARSER ................................................................................................... 19
5.2.7 _WAVE_PARSER ................................................................................................... 19
5.2.8 _XMF_PARSER ...................................................................................................... 19
5.3 Effects Options .............................................................................................................. 19
5.3.1 _ENHANCER_ENABLED ....................................................................................... 19
5.3.2 _COMPRESSOR_ENABLED ................................................................................. 19
5.3.3 _WOW_ENABLED .................................................................................................. 20
6 Host Wrapper (HW) Interface .............................................................................................. 20
6.1 Initialization and Shutdown ............................................................................................ 20
6.1.1 EAS_HWInit ............................................................................................................ 20
6.1.2 EAS_HWShutdown ................................................................................................. 20
6.2 Memory Functions ......................................................................................................... 21
6.2.1 EAS_HWMalloc ...................................................................................................... 21
6.2.2 EAS_HWFree ......................................................................................................... 21
6.2.3 EAS_HWMemCpy .................................................................................................. 21
6.2.4 EAS_HWMemSet ................................................................................................... 21
6.3 File I/O Functions .......................................................................................................... 21
6.3.1 EAS_HWOpenFile .................................................................................................. 21
6.3.2 EAS_HWCloseFile .................................................................................................. 21
6.3.3 EAS_HWReadFile .................................................................................................. 22
6.3.4 EAS_HWGetByte .................................................................................................... 22
6.3.5 EAS_HWGetWord .................................................................................................. 22
6.3.6 EAS_HWGetDWord ................................................................................................ 22
6.3.7 EAS_HWFilePos ..................................................................................................... 22
6.3.8 EAS_HWFileSeek ................................................................................................... 22
6.3.9 EAS_HWFileLength ................................................................................................ 22
6.3.10 EAS_HWDupHandle ............................................................................................. 23
6.4 Hardware Functions ...................................................................................................... 23
6.4.1 EAS_HWVibrate ..................................................................................................... 23
6.4.2 EAS_HWLED .......................................................................................................... 23
6.5 Performance Functions ................................................................................................. 23
6.5.1 EAS_HWYield ......................................................................................................... 23
7 Memory Models ................................................................................................................... 24
8 Debug Message Reporting ................................................................................................. 24
8.1 Reporting Functions ...................................................................................................... 24
8.1.1 EAS_ReportEx ........................................................................................................ 24
8.1.2 EAS_Report ............................................................................................................ 24
8.1.3 EAS_ReportX .......................................................................................................... 25
8.1.4 EAS_SetDebugLevel .............................................................................................. 25
8.1.5 EAS_SetDebugFile ................................................................................................. 25
9 Performance Tuning ............................................................................................................. 25
9.1 Controlling Average CPU Usage ................................................................................... 25
Copyright 2008 SONIC NETWORK, INC. EAS Version 3.6 Page 3/34
9.2 Controlling Peak CPU Usage ........................................................................................ 26
9.3 Multi-tasking Operation .................................................................................................. 26
10 Wave File Output .............................................................................................................. 26
10.1 Functions ..................................................................................................................... 26
10.1.1 WaveFileCreate .................................................................................................... 26
10.1.2 WaveFileWrite ....................................................................................................... 26
10.1.3 WaveFileClose ...................................................................................................... 26
11 Using the EAS Library ........................................................................................................ 27
11.1 Detailed Walkthrough of Interface to EAS Library ........................................................ 27
12 Optional Modules ............................................................................................................... 29
12.1 Standalone Audio Mixer ............................................................................................... 29
12.2 SRS WOW XT Interface .............................................................................................. 29
12.3 Wave File Parser ......................................................................................................... 30
Copyright 2008 SONIC NETWORK, INC. EAS Version 3.6 Page 4/34
1 Introduction
1.1 Abstract
This document outlines the implementation of the Sonic Network Inc Embedded Audio
Synthesizer Library. This document provides a high level overview of the EAS synthesizer
interface, and does not discuss the underlying EAS synthesizer. The Sonic EAS Library is
implemented using a combination of fixed point C and assembly code for a variety of
processors.
1.2 Intended Audience
This document is intended for the engineer integrating the Embedded Audio Synthesizer into
the target system.
1.3 Abbreviations
EAS Embedded Audio Synthesis
Synth Synthesizer
HW Host Wrapper
CM Configuration Module
1.4 Revision History
Rev Date Author Comments
1.00 Feb 4, 2003 jt Initial Draft
1.01 Sep 3, 2004 jt Revised for new public interface
1.02 Sep 22, 2004 jt Added new functions to public interface,
SynthStop, SynthSetStopTime, SynthPause, and
SynthResume
2.00 Feb 7, 2005 jt Revised for new (Gen3.2) public interface
2.01 May 24, 2005 dls Added new API calls
2.02 Jun 16, 2005 dls Documented streaming MIDI interface, minor
updates
2.03 Jul 9, 2005 dls Documented EAS_SetParameter,
EAS_GetParameter, SRS WOW XT interface
2.04 Jul 16, 2005 dls Documented additional ringtone parsers
2.05 Jul 16, 2005 jah Added Mobile DLS/XMF parser define
2.06 Jul 27, 2005 dls Documented metadata retrieval functions and
wave file parser
3.00 Feb 9, 2006 dls Updates for Version 3.4
4.00 May 18, 2006 dls Updates for Version 3.5
4.01 Jun 2, 2006 dls Updated metadata functions and minor cleanup
4.02 Jul 21, 2006 dls Added EAS_GetFileType function
5.00 Mar 8, 2007 dls Update for V3.6
5.01 Jul 2, 2007 dls Added EAS_SetPlayMode and
EAS_SetHeaderSearchFlag
1.5 References and related documents
1 Complete MIDI 1.0 Detailed Specification – MIDI Manufacturers Association
2 Scalable Polyphony MIDI Specification & Profiles – MIDI Manufacturers Association
3 WOW® XT For ARM Usage – SRS Labs, Inc.
Copyright 2008 SONIC NETWORK, INC. EAS Version 3.6 Page 5/34
