Académique Documents
Professionnel Documents
Culture Documents
Products
Pricing
Resources
Blog
Sign-in
Download
A few months ago, the developers from Yobonja (who made hits like Blast Monkeys)
posted they discovered a Hidden Audio Module in the Corona SDK. Since Daily
Builds have been temporarily suspended until Aug 2, this seemed like a good time to
talk about the secret/undocumented audio APIs in Corona to give you something to
play with in the meantime. But before I go on, let me set up the disclaimer and
ground rules.
Disclaimer
The features I talk about in this article are untested, unsupported, and we
reserve the right to remove these APIs at any time. Use at your own risk. We do
not want these features to be support issues for us, so do not send us bug reports
with code using any of these features. We also do not want to see complaints
and griping about these features. Intelligent discussion and constructive
criticism are welcome provided that everything is clearly marked so we can
easily filter things out when we need to focus on our official supported paths.
Finally, do not make us regret publicly talking about these secret features. If this
is a negative experience for us, we will never do anything like this again. Forum
users should police each other.
LOOKING FOR
PREMIUM
MONETIZATION
OPTIONS?
BUY PRO
or test out Corona
SDK Starter for free.
STARTING BUILDING
A
Game
Business app
Educational app
The possibilities are
endless!
CATEGORIES
Select Category
wrapper library around OpenAL which we use in Corona. The API of ALmixer itself
was influenced by another library called SDL_mixer. Part of the design of ALmixer
was to make OpenAL easier to use while still being able to allow access to OpenAL
features. Coronas first goal of adopting ALmixer was to pass on the ease of use of
using OpenAL to our users. But we are also interested in passing on the power of
OpenALs features to our users as well. The secret audio APIs in Corona are our initial
thoughts/groundwork in making this happen.
So thus far in Corona, we have hidden the details of how OpenAL works and we let
users just think of it as a sound playing engine. But to really appreciate what OpenAL
can do, how it works, and how the secret APIs apply to you, it is worth describing the
high level design of OpenAL.
The Design of OpenAL in a Nutshell
OpenAL has three fundamental object types: buffers, sources, and the listener.
Buffers are essentially your audio data. We hide all those details from you. In Corona,
all you ever see is loadSound and loadStream which hides lots of complex code from
you.
Sources are things that emit sounds. You might think of them as your game objects,
like a missile which has a rocket sound or an exploding ship that has a boom sound.
The listener is essentially where your head & ears are in the game. Do not confuse
this with the Corona notion of a listener which is a callback function. In OpenAL, the
listener is literally the object that is listening to (hearing) all sounds in your
application.
In Corona, thus far, youve been using the notion of channels to control different
simultaneously playing sounds. But channels as you know them in Corona dont
really exist in OpenAL; we made them up. In OpenAL, each sound emitting object is a
source. A source has multiple properties like gain (volume), position, velocity, etc. So
the secret formula in Corona is that, every channel maps to a different OpenAL
source object. And conversely, every OpenAL source maps to a Corona channel.
Understanding this will let you exploit a backdoor API we exposed in Corona to
OpenAL directly. This is where the fun begins.
Secret Audio APIs Part 1: luaal (Lua/OpenAL bindings)
We wrote a partial direct interface between Lua and OpenAL. This will let you call an
assortment of OpenAL functions directly in Lua. There are several families of
functions in OpenAL. The ones of interest to you are the functions that set properties
Easily create high-quality PDFs from your web pages - get a business license!
The value 2.0 shifts the pitch up by one octave for the source you designate.
Another example is to set the position on a source with the alSource3f function:
alSource3f(source_id, AL_POSITION, 5.0, 0.0, 0.0);
This would set that sources position to the coordinate <5,0,0> in your world.
Similarly, there are functions that control the listener which is where your head/ears
are in the world. Similar to sources, the listener also has its own properties such as
position, velocity, etc. Once you define properties on your sources and the listener,
OpenAL automatically computes how the final audio output is supposed to sound
and plays this output to your speakers.
alListener3f(AL_POSITION, 0.0, 0.0, 0.0);
This would set the listener (your ears in the game) position to <0,0,0> in your world
(<0,0,0> also happens to be the OpenAL default). So if you play the above sound
(source) at <5,0,0>, the sound will come out of the right speaker because the source
is to the right of the listener.
With our Lua bindings, you could call the above like:
al.Source(source_id, al.PITCH, 2.0)
al.Source(source_id, al.POSITION, 5.0, 0.0, 0.0)
al.Listener(al.POSITION, 0.0, 0.0, 0.0)
See the bottom of this page for a list of more OpenAL functions and constants we
exposed.
Secret Audio APIs Part 2: Mapping between Corona channels and OpenAL sources
But now the question is, How do I get a source id? Well, this is the other half of to the
secret audio APIs in Corona. Well, as I stated earlier, every Corona channel maps to
an OpenAL source. So you just need a way of converting a channel to a source.
Easily create high-quality PDFs from your web pages - get a business license!
This is good, but we have even something better. Unbeknownst to everybody, we did
something clever and took advantage of Luas multiple return arguments feature. So
every public audio function in Corona that returns a channel, also secretly returns a
source id as a second parameter.
local mychannel, mysource = audio.play( mySound )
Similarly, every public audio function in Corona that takes a channel=} table
parameter, also takes an alternative source= table parameter:
audio.setVolume(0.5, {source= mysource})
With pride, I can say that this was all designed/planned in advance and not some
horrible kludge. And all of this (including luaal) has been in Corona since the very
first release of our new audio engine way back in Build 222!
OpenAL is stateful
One important ground rule to understand is that OpenAL is stateful, meaning, if you
change a property, it stays that way until you change it again later. Some of you have
noticed already in Corona that when you change a volume on a channel including
using fade-in/fade-out, the volume is persistent until you change it again. This is the
reason. So remember that when you change a property in OpenAL, it stays that way
until you change it again.
The Long Term Goal
We want to expose OpenAL features to Corona, but we want to find the correct
balance of ease of use and power. However, as some of you know, Google has
completely dropped the ball on audio and most of our engineering resources have
been diverted to improving the basics on Android instead of working on new
features. So in revealing these secret APIs, we are interested in seeing what you
come up with and how you use them. Intelligent feedback on the forums is welcome,
but be aware we may be slow to respond if at all. And who knows, maybe, one of you
will write something so good that we will ask to incorporate directly in Corona.
Easily create high-quality PDFs from your web pages - get a business license!
Final thoughts:
Please use with care. Again, none of this stuff is supported or even necessarily
tested. We do reserve the right to change the APIs or remove them entirely, so dont
complain if we break you. Please dont make us regret discussing these secret APIs.
Additional Information:
The OpenAL Programmers
Guide: http://connect.creativelabs.com/openal/Documentation/OpenAL_Programmer
s_Guide.pdf This is the official online guide for OpenAL.
Beginning iPhones Game Development: http://playcontrol.net/iphonegamebook I
wrote the worlds first and only book that attempts to cover OpenAL
comprehensively. Chapter 11 covers all the OpenAL 3D features in detail.
ALmixer: http://playcontrol.net/opensource/ALmixer/ open source
luaal
http://www.assembla.com/code/almixer_isolated/mercurial/nodes/Isolated/luaal/lu
aal.c?rev=c07dbd386ded62c8c832585c2c1d2e74eb44c34c open source
ALexplorer: http://developer.anscamobile.com/code/alexplorer A Corona example
program from our very own Alix, showing off some of these features
Appendix A: Examples Summary
-- We secretly returned two values for functions that return channels
local mychannel, mysource = audio.play(mySound)
-- 1.0 is normal, 2.0 is up one octave, 0.5 is down one octave
al.Source(mysource, al.PITCH, 2.0);
-- moves the source position to left-of-center (x-axis) by 5 units
-- number values are x-axis, y-axis, z-axis
al.Source(mysource, al.POSITION, -5.0, 0.0, 0.0)
-- Note that all the audio APIs support "source" as a key name where we've documented
"channel" as a key name, e.g.
audio.setVolume(0.5, {source=mysource})
-- Also, we have two functions that get convert one to the other
mysource = audio.getSourceFromChannel(1)
mychannel = audio.getChannelFromSource(mysource)
Easily create high-quality PDFs from your web pages - get a business license!
Here is the mapping of some of the constants we exposed. Lua is on the left, C is on
the right. In Corona, you need to prefix al. to everything, e.g. PITCH is al.PITCH.
{ "NONE", AL_NONE },
{ "FALSE", AL_FALSE },
{ "TRUE", AL_TRUE },
{ "SOURCE_RELATIVE", AL_SOURCE_RELATIVE },
{ "CONE_INNER_ANGLE", AL_CONE_INNER_ANGLE },
{ "CONE_OUTER_ANGLE", AL_CONE_OUTER_ANGLE },
{ "PITCH", AL_PITCH },
{ "POSITION", AL_POSITION },
{ "DIRECTION", AL_DIRECTION },
{ "VELOCITY", AL_VELOCITY },
{ "ORIENTATION", AL_ORIENTATION },
{
{
{
{
"REFERENCE_DISTANCE", AL_REFERENCE_DISTANCE },
"ROLLOFF_FACTOR", AL_ROLLOFF_FACTOR },
"CONE_OUTER_GAIN", AL_CONE_OUTER_GAIN },
"MAX_DISTANCE", AL_MAX_DISTANCE },
Easily create high-quality PDFs from your web pages - get a business license!
{ "DOPPLER_FACTOR", AL_DOPPLER_FACTOR },
{ "DOPPLER_VELOCITY", AL_DOPPLER_VELOCITY },
{ "SPEED_OF_SOUND", AL_SPEED_OF_SOUND },
{ "DISTANCE_MODEL", AL_DISTANCE_MODEL },
{ "INVERSE_DISTANCE", AL_INVERSE_DISTANCE },
{ "INVERSE_DISTANCE_CLAMPED", AL_INVERSE_DISTANCE_CLAMPED },
{ "LINEAR_DISTANCE", AL_LINEAR_DISTANCE },
{ "LINEAR_DISTANCE_CLAMPED", AL_LINEAR_DISTANCE_CLAMPED },
{ "EXPONENT_DISTANCE", AL_EXPONENT_DISTANCE },
{ "EXPONENT_DISTANCE_CLAMPED", AL_EXPONENT_DISTANCE_CLAMPED },
For a comprehensive list and understanding of whats exposed, you can look at the
source code of luaal.c.
This entry was posted in Lua, Tutorials, Tips and Demos and tagged ALmixer, luaal, OpenAL, secret
APIs. Bookmark the permalink.
47 comments on The
secret/undocumented audio APIs in
Corona SDK
Carlos Icaza says:
July 27, 2011 at 9:48 am
Reply
Chris says:
Easily create high-quality PDFs from your web pages - get a business license!
Very nice!
So now I could actually make a panning effect and simulate
helicopter flights
Reply
Reply
Taka says:
July 27, 2011 at 11:06 am
Reply
ewing says:
July 27, 2011 at 11:20 am
very own Alix that shows off some of these hidden features.
See ALexplorer at:
http://developer.anscamobile.com/code/alexplorer
Reply
ewing says:
July 27, 2011 at 11:27 am
Androids audio problems are no secret. Here are some links I found
searching with Google.
http://code.google.com/p/android/issues/detail?id=3434
http://kile.stravaganza.org/blog/post/android-audio-api-sucks
http://www.badlogicgames.com/wordpress/?p=1315
http://groups.google.com/group/androidndk/browse_thread/thread/29f88a99dc954c71
http://mindtherobot.com/blog/555/android-audio-problems-hiddenlimitations-and-opensl-es/
http://music.columbia.edu/pipermail/portaudio/2010December/011146.html
Reply
Taka says:
July 27, 2011 at 11:51 am
Reply
ewing says:
July 27, 2011 at 12:01 pm
Reply
Reply
OMG thank you so much Carlos and the rest of the Corona staff! I
have been waiting for something like this for so long and as it
happens im in the middle of creating a music app right now! I am
going to start playing around with this ASAP. Again thank you, hope i
can manage some cool uses. Maybe i can finally port my app I made
with GameSalad(yuck!) to Corona!
Reply
Alberto says:
July 27, 2011 at 5:22 pm
Great post, and to give some feedback I love this approach. Provide a
simple to use interface that developers can quickly get going with
and then provide additional functionality via access to the lower level
library for developers that want more control Win/Win!
Reply
Has anyone been able to get the al.VELOCITY to work? I would like to
Easily create high-quality PDFs from your web pages - get a business license!
Reply
ewing says:
July 27, 2011 at 7:45 pm
OpenAL velocity is not what you think. Velocity represents the speed
of a sound source (object) moving through space. Think of a missile
traveling across the screen. Velocity values work in conjunction with
the Doppler Effect to pitch shift the sound effect.
To change the playback speed of a source, you can change the
al.PITCH which happens to change the speed at which a sound is
played back at. But be aware that OpenAL does not support pitch
corrected speed scaling.
Reply
Reply
Easily create high-quality PDFs from your web pages - get a business license!
popo says:
August 2, 2011 at 9:50 am
Reply
Jason says:
March 15, 2013 at 4:47 am
Reply
One of the things that makes Corona superior to almost any other
mobile development environment is the access to up-to-the-minute
changes. Publishing this secret API is in the same spirit, and I hope
that it is a positive experience for Ansca. As a developer, it is great to
be able to see where things are going and try out new ideas even if
they are just experiments. Thanks for trusting us with the
information!
Reply
Easily create high-quality PDFs from your web pages - get a business license!
Just to add: Thanks for disclosing this stuff here. I am really looking
forward to play around with more real-time audio creation features,
especially for the use of creating music generation toys, or just more
interesting dynamic music in a game.
Reply
bob says:
December 9, 2011 at 12:25 am
Hooray!
Reply
Alberto says:
January 17, 2012 at 9:02 am
Its not possible an echo effect with this API, isnt it?
It seems only adding EFX extension to openAL (with effect objects)
could be, and i figure out this is not possible in Corona yet.
Reply
Reply
Alberto says:
January 18, 2012 at 8:46 am
Reply
ewing says:
January 18, 2012 at 12:41 pm
Reply
Alberto says:
January 19, 2012 at 8:39 am
Thanks ewing!
Reply
Easily create high-quality PDFs from your web pages - get a business license!
peter says:
February 22, 2012 at 2:10 pm
Reply
ewing says:
February 23, 2012 at 2:22 pm
Reply
John says:
March 18, 2012 at 5:44 pm
Reply
Easily create high-quality PDFs from your web pages - get a business license!
ewing says:
March 18, 2012 at 6:50 pm
They should work, though its not horribly tested. But the
code paths for this are identical on all platforms. Make
sure your audio is mono.
Reply
John says:
March 18, 2012 at 9:46 pm
Thanks for your quick reply. I hadnt considered making sure the
audio files were mono. However, Im still having no luck. I even
explicitly set al.ROLLOFF_FACTOR to make sure it wasnt set to 0
somehow. I also tried running ALExplorer with no luck (I had to install
Corona Build 591 to get it to run). The sound would play, but equally
through both channels no matter how I set the sliders. Here are my
system details, if it might make a difference:
Windows: Vista SP1
Android: HTC Desire Android 2.2
Corona: build 591 and 731
Reply
ewing says:
March 18, 2012 at 10:23 pm
Does pitch work for you? I have seen it work successfully on Android.
Reply
Easily create high-quality PDFs from your web pages - get a business license!
John says:
March 19, 2012 at 12:53 am
Reply
John, you should search/post on the forums. You might get more help
there.
Reply
John says:
March 20, 2012 at 8:37 pm
Reply
ewing says:
March 25, 2012 at 12:19 pm
Reply
Easily create high-quality PDFs from your web pages - get a business license!
Alan says:
July 30, 2012 at 6:33 am
Im having the same problem that John had, in that no matter what
values I set for the position of the sound and listener I get the same
sound through both the left and right channels. Ive tried stereo and
mono sounds, but no luck.
Has anyone ever actually got this to work in Corona? I had no
problems changing the pitch of a sound, so thought the position
would be just as simple.
Reply
Check out OpenAL Explorer by Plaino LLC. This was written in Corona.
http://itunes.apple.com/us/app/openal-explorer/id504578957?mt=8
I thought he posted the source code GitHub.
Reply
Alan says:
July 31, 2012 at 3:11 am
Turns out that using mono files DID work, the problem was the
values I was setting to reposition the sound. I assumed it would use
game world values, i.e. -screenWidth for left and +screenWidth for
the right. Changing the values to -1 for left and +1 for right fixed it.
Reply
Easily create high-quality PDFs from your web pages - get a business license!
Alan says:
July 31, 2012 at 3:35 am
Also, I can now ONLY have exactly 50/50 left/right, 100% left or 100%
right. Even a tiny adjustment (0.0001) to the right makes the sound
entirely shift to the right channel. This is still better than I had
before, but I wouldve preferred an 80/20 split.
Eric Wing: Thank you, I just downloaded the app and can see how
changing the values affects the sound but if I use the xyz values for
my source and listener I dont get quite the same effect. Ive tried
searching for the source code for OpenAL Explorer but have had no
luck.
Reply
mike says:
August 7, 2012 at 11:55 am
Reply
Greg says:
August 27, 2012 at 5:14 pm
Reply
Reply
Don says:
January 13, 2013 at 7:49 pm
I tried to study the SuperAudio class, but have not yet made sense of
it. I dont need 3-d spacial effects, but just the ability to pan a sound,
slowly, from left to right while it is playing. My higher math skills
arent what they were in grade eleven. Ive tried simply adjusting the
listener X-axis value, to no avail. I can make a sound come out on the
left, center or right, but not change it while it plays. Does anyone
have a simple example of panning left to right on the fly that works
on IOS 6? Thanks in advance
Reply
monta says:
February 7, 2013 at 9:41 am
thanks
Reply
kumar ks says:
September 27, 2013 at 5:06 am
Hi ,
I am new to corona, I am developing an app , where i am using lot of
mp3 files for narration purpose.
I am here using audio.loadStream() and audio.play() along with
audio.pause(). What actually happens is my app is running for 9 to 12
times properly, after that it just stuck and i have to re launch the app
. Whats the problem here , am i using the api properly , or anything i
have to modify . pls tell me as soon as possible .
Reply
Danijel says:
January 10, 2014 at 2:35 am
Reply
Terry says:
February 19, 2014 at 9:59 am
Danijel:
Easily create high-quality PDFs from your web pages - get a business license!
Reply
Reply
Leave a Reply
Your email address will not be published. Required fields are marked *
Easily create high-quality PDFs from your web pages - get a business license!
Name *
Email *
Website
Start typing...
You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title="">
<b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>
Post Comment
Products
Resources
Get Corona
About
Corona SDK
Forum
Jobs
Enterprise
Documentation
Buy Pro
Contact
CoronaCards
Corona University
Buy Enterprise
Buy CoronaCards
Copyright 2009-2014 Corona Labs. A Fuse Powered Company. All rights reserved.
Privacy Policy Terms and Conditions
Easily create high-quality PDFs from your web pages - get a business license!
Social