OpenSL ES Specification 1.0.1

OpenSL ES Specification
Version 1.0.1
September 24th 2009

Copyright © 2007-2009 The Khronos Group Inc. All Rights Reserved.
This specification is protected by copyright laws and contains material proprietary to the
Khronos Group, Inc. It or any components may not be reproduced, republished, distributed,
transmitted, displayed, broadcast, or otherwise exploited in any manner without the express
prior written permission of the Khronos Group. You may use this specification for
implementing the functionality therein, without altering or removing any trademark, copyright
or other notice from the specification, but the receipt or possession of this specification does not
convey any rights to reproduce, disclose, or distribute its contents, or to manufacture, use, or
sell anything that it may describe, in whole or in part.
Khronos Group grants express permission to any current Promoter, Contributor or Adopter
member of Khronos to copy and redistribute UNMODIFIED versions of this specification in
any fashion, provided that NO CHARGE is made for the specification and the latest available
update of the specification for any version of the API is used whenever possible. Such
distributed specification may be reformatted AS LONG AS the contents of the specification are
not changed in any way. The specification may be incorporated into a product that is sold as
long as such product includes significant independent work developed by the seller. A link to
the current version of this specification on the Khronos Group website should be included
whenever possible with specification distributions.
Khronos Group makes no, and expressly disclaims any, representations or warranties, express
or implied, regarding this specification, including, without limitation, any implied warranties of
merchantability or fitness for a particular purpose or non-infringement of any intellectual
property. Khronos Group makes no, and expressly disclaims any, warranties, express or implied,
regarding the correctness, accuracy, completeness, timeliness, and reliability of the
specification. Under no circumstances will the Khronos Group, or any of its Promoters,
Contributors or Members or their respective partners, officers, directors, employees, agents or
representatives be liable for any damages, whether direct, indirect, special or consequential
damages for lost revenues, lost profits, or otherwise, arising from or in connection with these
materials.
SAMPLE CODE and EXAMPLES, as identified herein, are expressly depicted herein with a
“grey” watermark and are included for illustrative purposes only and are expressly outside of
the Scope as defined in Attachment A - Khronos Group Intellectual Property (IP) Rights Policy
of the Khronos Group Membership Agreement. A Member or Promoter Member shall have no
obligation to grant any licenses under any Necessary Patent Claims covering SAMPLE CODE
and EXAMPLES.
Khronos, OpenKODE, OpenVG, OpenSL ES and OpenMAX are trademarks of the Khronos
Group Inc. OpenCL is a trademark of Apple Inc., COLLADA is a trademark of Sony
Computer Entertainment Inc. and OpenGL is a registered trademark of Silicon Graphics Inc.
used under license by Khronos. All other product names, trademarks, and/or company names
are used solely for identification and belong to their respective owners.

Table of Contents
PART 1: USER MANUAL .........................................................................................1
1 OVERVIEW .....................................................................................................2
1.1 PURPOSE OF THIS DOCUMENT............................................................................2
1.1.1 About the Khronos Group.....................................................................2
1.2 SCOPE.......................................................................................................2
1.3 INTENDED AUDIENCE......................................................................................2
1.4 A BRIEF HISTORY OF OPENSL ES.......................................................................3
1.5 RELATIONSHIP TO OPENMAX AL 1.0...................................................................3
1.6 CONVENTIONS USED ......................................................................................5
1.6.1 Parameter Range Notation ...................................................................5
1.6.2 Format and Typographic Conventions ....................................................6
1.7 DEFINITION OF TERMS ....................................................................................6
1.8 ACKNOWLEDGEMENTS.....................................................................................6
2 FEATURES AND PROFILES ..............................................................................8
2.1 MOTIVATION ...............................................................................................8
2.2 PROFILE DEFINITION ......................................................................................9
2.3 PROFILES ...................................................................................................9
2.4 OPTIONALITY RULES OF FEATURES AND PROFILES...................................................11
2.5 PROFILE NOTES ..........................................................................................12
2.6 BEHAVIOR FOR UNSUPPORTED FEATURES.............................................................12
3 DESIGN OVERVIEW......................................................................................13
3.1 OBJECT MODEL ..........................................................................................13
3.1.1 Objects and Interfaces.......................................................................13
3.1.2 Getters and Setters...........................................................................15

3.1.3 Representation in Code...................................................................... 16
3.1.4 The SLObjectItf Interface................................................................... 17
3.1.5 The Engine Object and SLEngineItf Interface ........................................ 17
3.1.6 The Relationship Between Objects and Interfaces.................................. 18
3.1.7 The SLDynamicInterfaceManagementItf Interface.................................. 20
3.1.8 Resource Allocation........................................................................... 20
3.2 THREADING MODEL...................................................................................... 22
3.2.1 Mode of Operation ............................................................................ 22
3.2.2 Thread Safety .................................................................................. 22
3.3 NOTIFICATIONS.......................................................................................... 23
3.4 ERROR REPORTING ...................................................................................... 23
3.5 EXTENSIBILITY ........................................................................................... 24
3.5.1 Principles......................................................................................... 24
3.5.2 Permitted Modifications to Physical Code.............................................. 25
3.5.3 Extending Supported Interface Types .................................................. 25
3.5.4 Extending Supported Object Types...................................................... 25
3.5.5 Extending Method Parameter Ranges................................................... 26
3.5.6 Result Codes.................................................................................... 26
3.5.7 Interface ID Allocation Scheme........................................................... 26
3.5.8 Avoiding Naming Collisions................................................................. 26
4 FUNCTIONAL OVERVIEW..............................................................................28
4.1 OBJECT OVERVIEW ...................................................................................... 28
4.1.1 Engine Object................................................................................... 28
4.1.1.1 Devices ...................................................................................................29
4.1.2 Media Objects .................................................................................. 29
4.1.2.1 Data Source and Sink Structures.................................................................29

4.1.3 Metadata Extractor Object..................................................................30
4.1.4 Audio Output Mix Object ....................................................................30
4.1.5 LED Array Control Object ...................................................................31
4.1.6 Vibration Control Object.....................................................................31
4.2 SAMPLED AUDIO .........................................................................................32
4.2.1 Recommended Codec ........................................................................32
4.3 PLAYBACK OF MIDI .....................................................................................32
4.3.1 Support of Mobile DLS .......................................................................32
4.3.2 Programmatic Control of the MIDI Player..............................................33
4.4 3D AUDIO ................................................................................................33
4.4.1 3D Sources ......................................................................................34
4.4.1.1 3D Groups............................................................................................... 34
4.4.1.2 When is a Player Rendered in 3D?............................................................... 34
4.4.2 3D Parameters .................................................................................35
4.4.2.1 Coordinate System ................................................................................... 35
4.4.2.2 Precision ................................................................................................. 35
4.4.2.3 Interactivity............................................................................................. 36
4.4.3 Levels of 3D Sources.........................................................................36
4.4.4 3D Positioning Multi-Channel Players ...................................................36
4.4.4.1 3D and MIDI Players ................................................................................. 36
4.4.5 Object Relationships..........................................................................36
4.5 EFFECTS ..................................................................................................37
4.5.1 Effects Architecture...........................................................................37
4.5.2 Bass Boost.......................................................................................37
4.5.3 Equalization .....................................................................................38
4.5.4 Virtualization....................................................................................38
4.5.5 Reverberation...................................................................................38