Properties
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.
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.Optional method
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.If a volume is outside[0, 1], return INVALID_ARGUMENTS
|
|
updateSourceMetadata
updateSourceMetadata (SourceMetadata sourceMetadata)
Called when the metadata of the stream's source has been changed.
Details |
Parameters |
sourceMetadata
|
Description of the audio that is played by the clients.
|
|
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.Optional method
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.Optional method
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 |
|
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.
If no callback was previously set, the method should be a no-op and return OK.
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 |
|
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'.Optional method
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.
Optional method
Details |
Generates |
retval
|
operation completion status.
|
frames
|
count of presented audio frames.
|
timeStamp
|
associated clock time.
|
|
selectPresentation
selectPresentation (int32_t presentationId, int32_t programId)
generates (Result retval)
Selects a presentation for decoding from a next generation media stream(as defined per ETSI TS 103 190-2)and a program within the presentation.Optional method
Details |
Parameters |
presentationId
|
selected audio presentation.
|
programId
|
refinement for the presentation.
|
|
Generates |
retval
|
operation completion status.
|
|