Package: android.hardware.audio@2.0

IStreamOut

interface IStreamOut extends IStream

Properties

Result

typedef android.hardware.audio@2.0::Result Result

WriteCommand

enum WriteCommand: int32_t

Commands that can be executed on the driver writer thread.

Details
Members
WRITE
GET_PRESENTATION_POSITION
GET_LATENCY

WriteStatus

struct WriteStatus {Result retval; WriteCommand replyTo; union Reply reply}

Data structure passed back to the client via status message queue of 'write' operation.

Possible values of 'retval' field:- OK, write operation was successful;- INVALID_ARGUMENTS, stream was not configured properly;- INVALID_STATE, stream is in a state that doesn't allow writes;- INVALID_OPERATION, retrieving presentation position isn't supported.

Details
Members
retval
replyTo
reply

Methods

getLatency

getLatency ()
generates (uint32_t latencyMs)

Return the audio hardware driver estimated latency in milliseconds.

Details
Generates
latencyMs
latency in milliseconds.

setVolume

setVolume (float left, float right)
generates (Result retval)

This method is used in situations where audio mixing is done in the hardware.This method serves as a direct interface with hardware, allowing to directly set the volume as apposed to via the framework.This method might produce multiple PCM outputs or hardware accelerated codecs, such as MP3 or AAC.

Details
Parameters
left
left channel attenuation, 1.0f is unity, 0.0f is zero.
right
right channel attenuation, 1.0f is unity, 0.0f is zero.
Generates
retval
operation completion status.

prepareForWriting

prepareForWriting (uint32_t frameSize, uint32_t framesCount)
generates (Result retval, fmq_sync<WriteCommand> commandMQ, fmq_sync<uint8_t> dataMQ, fmq_sync<WriteStatus> statusMQ, ThreadInfo threadInfo)

Set up required transports for passing audio buffers to the driver.

The transport consists of three message queues:-- command queue is used to instruct the writer thread what operation to perform;-- data queue is used for passing audio data from the client to the driver;-- status queue is used for reporting operation status(e.g.amount of bytes actually written or error code).

The driver operates on a dedicated thread.The client must ensure that the thread is given an appropriate priority and assigned to correct scheduler and cgroup.For this purpose, the method returns identifiers of the driver thread.

Details
Parameters
frameSize
the size of a single frame, in bytes.
framesCount
the number of frames in a buffer.
Generates
retval
OK if both message queues were created successfully.INVALID_STATE if the method was already called.INVALID_ARGUMENTS if there was a problem setting up the queues.
commandMQ
a message queue used for passing commands.
dataMQ
a message queue used for passing audio data in the format specified at the stream opening.
statusMQ
a message queue used for passing status from the driver using WriteStatus structures.
threadInfo
identifiers of the driver's dedicated thread.

getRenderPosition

getRenderPosition ()
generates (Result retval, uint32_t dspFrames)

Return the number of audio frames written by the audio DSP to DAC since the output has exited standby.

Details
Generates
retval
operation completion status.
dspFrames
number of audio frames written.

getNextWriteTimestamp

getNextWriteTimestamp ()
generates (Result retval, int64_t timestampUs)

Get the local time at which the next write to the audio driver will be presented.The units are microseconds, where the epoch is decided by the local audio HAL.

Details
Generates
retval
operation completion status.
timestampUs
time of the next write.

setCallback

setCallback (IStreamOutCallback callback)
generates (Result retval)

Set the callback interface for notifying completion of non-blocking write and drain.

Calling this function implies that all future 'write' and 'drain' must be non-blocking and use the callback to signal completion.

'clearCallback' method needs to be called in order to release the local callback proxy on the server side and thus dereference the callback implementation on the client side.

Details
Parameters
callback
Generates
retval
operation completion status.

clearCallback

clearCallback ()
generates (Result retval)

Clears the callback previously set via 'setCallback' method.

Warning:failure to call this method results in callback implementation on the client side being held until the HAL server termination.

Details
Generates
retval
operation completion status:OK or NOT_SUPPORTED.

supportsPauseAndResume

supportsPauseAndResume ()
generates (bool supportsPause, bool supportsResume)

Returns whether HAL supports pausing and resuming of streams.

Details
Generates
supportsPause
true if pausing is supported.
supportsResume
true if resume is supported.

pause

pause ()
generates (Result retval)

Notifies to the audio driver to stop playback however the queued buffers are retained by the hardware.Useful for implementing pause/resume.Empty implementation if not supported however must be implemented for hardware with non-trivial latency.In the pause state, some audio hardware may still be using power.Client code may consider calling 'suspend' after a timeout to prevent that excess power usage.

Implementation of this function is mandatory for offloaded playback.

Details
Generates
retval
operation completion status.

resume

resume ()
generates (Result retval)

Notifies to the audio driver to resume playback following a pause.Returns error INVALID_STATE if called without matching pause.

Implementation of this function is mandatory for offloaded playback.

Details
Generates
retval
operation completion status.

supportsDrain

supportsDrain ()
generates (bool supports)

Returns whether HAL supports draining of streams.

Details
Generates
supports
true if draining is supported.

drain

drain (AudioDrain type)
generates (Result retval)

Requests notification when data buffered by the driver/hardware has been played.If 'setCallback' has previously been called to enable non-blocking mode, then 'drain' must not block, instead it must return quickly and completion of the drain is notified through the callback.If 'setCallback' has not been called, then 'drain' must block until completion.

If 'type' is 'ALL', the drain completes when all previously written data has been played.

If 'type' is 'EARLY_NOTIFY', the drain completes shortly before all data for the current track has played to allow time for the framework to perform a gapless track switch.

Drain must return immediately on 'stop' and 'flush' calls.

Implementation of this function is mandatory for offloaded playback.

Details
Parameters
type
type of drain.
Generates
retval
operation completion status.

flush

flush ()
generates (Result retval)

Notifies to the audio driver to flush the queued data.Stream must already be paused before calling 'flush'.

Implementation of this function is mandatory for offloaded playback.

Details
Generates
retval
operation completion status.

getPresentationPosition

getPresentationPosition ()
generates (Result retval, uint64_t frames, TimeSpec timeStamp)

Return a recent count of the number of audio frames presented to an external observer.This excludes frames which have been written but are still in the pipeline.The count is not reset to zero when output enters standby.Also returns the value of CLOCK_MONOTONIC as of this presentation count.The returned count is expected to be 'recent', but does not need to be the most recent possible value.However, the associated time must correspond to whatever count is returned.

Example:assume that N+M frames have been presented, where M is a 'small' number.Then it is permissible to return N instead of N+M, and the timestamp must correspond to N rather than N+M.The terms 'recent' and 'small' are not defined.They reflect the quality of the implementation.

Details
Generates
retval
operation completion status.
frames
count of presented audio frames.
timeStamp
associated clock time.