audio.dispose()

Description:

Releases audio memory associated with the handle.

Syntax:

1
audio.dispose( audioHandle )

Example:

laserSound = audio.loadSound( "laserSound.wav" )
backgroundMusic = audio.loadStream( "backgroundMusic.m4a" )
audio.dispose( laserSound )
audio.dispose( backgroundMusic )
laserSound = nil  -- This makes sure we can't use the handle again
backgroundMusic = nil  -- This makes sure we can't use the handle again

Parameters:

audioHandle
Object: The handle (aka "object") returned by the audio.load* functions that you want to free.

Returns:
Remarks:

You must not use the handle once the memory is freed. The audio should not be active (playing or paused) on any channel when you try to free it.

Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    Build 2011.222
  • Windows:
    Build 2011.222
  • iOS:
    Build 2011.222
  • Android:
    Build 2011.222

Replies

jpot328
User offline. Last seen 8 years 36 weeks ago. Offline
Joined: 31 Jan 2011

Total noob, so I apologize in advance for my ignorance. As a simplified example, if I had the following code, the channels (laserChannel, backgroundChannel) do not need to be disposed of, correct?

1
2
3
4
5
6
7
8
9
10
laserSound = audio.loadSound( "laserSound.wav" )
backgroundMusic = audio.loadStream( "backgroundMusic.m4a" )
--
laserChannel = audio.play (laserSound)
backgroundChannel = audio.play (backgroundMusic)
--
audio.dispose( laserSound )
audio.dispose( backgroundMusic )
laserSound = nil  -- This makes sure we can't use the handle again
backgroundMusic = nil  -- This makes sure we can't use the handle again

In other words, I don't need to include the following as well, right?

1
2
audio.dispose( laserChannel )
audio.dispose( backgroundChannel )

Lastly, is there a program that shows memory content currently being used by the Corona simulator?

Thanks!

Shaunathan
User offline. Last seen 9 years 14 weeks ago. Offline
Joined: 18 Jan 2011

I would also like to know the answer to this. Can we get an Ansca reply?

ewing
User offline. Last seen 3 years 25 weeks ago. Offline
Alumni
Joined: 13 Jul 2010

You only call dispose on sound handles (things returned by loadSound/loadStream). You do not dispose channels.

We currently don't have a general memory usage indicator. There is one that tries to track texture memory, but nothing for sound at the moment.

For sound, you can roughly estimate. For loadSound, the size is the same as the audio file as if it were a completely uncompressed linear PCM file. So if your file was in an uncompressed .wav or .aiff, the size on disk is also the amount of RAM it takes.

izamojc
User offline. Last seen 8 years 12 weeks ago. Offline
Joined: 14 Apr 2011

It would be nice if audio.dispose() also nil-ified the handle since it already knows about it. Unless that increases the reference count, it seems strange to have to nil it manually since the handle is useless after being disposed. Is it not?

ewing
User offline. Last seen 3 years 25 weeks ago. Offline
Alumni
Joined: 13 Jul 2010

Actually izamojc, you have it a little backwards. In an ideal world, calling audio.dispose would never be needed and you would just set the reference to nil and the Lua garbage collector would take care of everything. However, waiting for the garbage collector to kick in is not ideal in some cases so hence we need audio.dispose. However, we can't violate Lua semantics so you technically still need to be responsible for your references. That said, there are some other things we can do to improve the memory management experience but they are tricky to implement so we need to do it right the first time or people will start seeing random crashes they can't control.