Well, IMHO this is a documentation bug!
If one person falls into a trap, it might be their fault, but if two do…
The documentation should say something like:
[list]
[]prepareToPlay() is guaranteed to be called at least once before the first call to getNextAudioBlock(), or before the first call to getNextAudioBlock() after releaseResouces() has been called.
[/]
[]releaseResources() is guaranteed to be called at least once after the last call to getNextAudioBlock() or prepareToPlay().
[/]
[]There are no other guarantees. Some streams will call prepareToPlay()/releaseResources() repeatedly if they stop and start, others will not. It is possible for releaseResources() to be called when prepareToPlay() has not.[/][/list]
Or another way to look at it that I find a little more intuitive:
[list][]An AudioStream can only have two states, prepared and released,
[/]
[]An AudioStream must always start and end its life in the released state…
[/]
[]…but getNextAudioBlock() can only be called if the AudioStream is in the prepared state.
[/]
[]prepareToPlay() puts the AudioStream into the prepared state; releaseResources() puts it in the released state.
[/]
[] prepareToPlay() and releaseResources() can be called at any time, in any order.[/][/list]