public interface TuSdkMediaCodec
限定符和类型 | 方法和说明 |
---|---|
boolean |
configure(android.media.MediaFormat format,
android.view.Surface surface,
int flags,
android.media.MediaDescrambler descrambler)
Configure a component to be used with a descrambler.
|
boolean |
configure(android.media.MediaFormat format,
android.view.Surface surface,
android.media.MediaCrypto crypto,
int flags)
Configures a component.
|
java.lang.Exception |
configureError()
配置错误信息
|
android.view.Surface |
createInputSurface()
Requests a Surface to use as the input to an encoder, in place of input buffers.
|
int |
dequeueInputBuffer(long timeoutUs)
Returns the index of an input buffer to be filled with valid data
or -1 if no such buffer is currently available.
|
int |
dequeueOutputBuffer(android.media.MediaCodec.BufferInfo info,
long timeoutUs)
Dequeue an output buffer, block at most "timeoutUs" microseconds.
|
boolean |
flush()
Flush both input and output ports of the component.
|
android.media.MediaCodecInfo |
getCodecInfo()
Get the codec info.
|
java.nio.ByteBuffer |
getInputBuffer(int index)
Returns a
cleared , writable ByteBuffer
object for a dequeued input buffer index to contain the input data. |
java.nio.ByteBuffer[] |
getInputBuffers()
Retrieve the set of input buffers.
|
android.media.MediaFormat |
getInputFormat()
Call this after
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int) returns successfully to
get the input format accepted by the codec. |
android.media.Image |
getInputImage(int index)
Returns a writable Image object for a dequeued input buffer
index to contain the raw input video frame.
|
android.os.PersistableBundle |
getMetrics()
Return Metrics data about the current codec instance.
|
java.lang.String |
getName()
Get the component name.
|
java.nio.ByteBuffer |
getOutputBuffer(int index)
Returns a read-only ByteBuffer for a dequeued output buffer
index.
|
java.nio.ByteBuffer[] |
getOutputBuffers()
Retrieve the set of output buffers.
|
android.media.MediaFormat |
getOutputFormat()
Call this after dequeueOutputBuffer signals a format change by returning
|
android.media.MediaFormat |
getOutputFormat(int index)
Returns the output format for a specific output buffer.
|
android.media.Image |
getOutputImage(int index)
Returns a read-only Image object for a dequeued output buffer
index that contains the raw video frame.
|
boolean |
isReleased()
是否已释放编解码器
|
boolean |
isStarted()
是否已启动编解码器
|
boolean |
queueInputBuffer(int index,
int offset,
int size,
long presentationTimeUs,
int flags)
After filling a range of the input buffer at the specified index
submit it to the component.
|
boolean |
queueSecureInputBuffer(int index,
int offset,
android.media.MediaCodec.CryptoInfo info,
long presentationTimeUs,
int flags)
Similar to
queueInputBuffer but submits a buffer that is
potentially encrypted. |
boolean |
release()
Free up resources used by the codec instance.
|
boolean |
releaseOutputBuffer(int index,
boolean render)
If you are done with a buffer, use this call to return the buffer to the codec
or to render it on the output surface.
|
boolean |
releaseOutputBuffer(int index,
long renderTimestampNs)
If you are done with a buffer, use this call to update its surface timestamp
and return it to the codec to render it on the output surface.
|
boolean |
reset()
Returns the codec to its initial (Uninitialized) state.
|
boolean |
setCallback(android.media.MediaCodec.Callback cb)
Sets an asynchronous callback for actionable MediaCodec events on the default
looper.
|
boolean |
setCallback(android.media.MediaCodec.Callback cb,
android.os.Handler handler)
Sets an asynchronous callback for actionable MediaCodec events.
|
boolean |
setInputSurface(android.view.Surface surface)
Configures the codec (e.g. encoder) to use a persistent input surface in place of input
buffers.
|
boolean |
setOnFrameRenderedListener(android.media.MediaCodec.OnFrameRenderedListener listener,
android.os.Handler handler)
Registers a callback to be invoked when an output frame is rendered on the output surface.
|
boolean |
setOutputSurface(android.view.Surface surface)
Dynamically sets the output surface of a codec.
|
boolean |
setParameters(android.os.Bundle params)
Communicate additional parameter changes to the component instance.
|
boolean |
setVideoScalingMode(int mode)
If a surface has been specified in a previous call to
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
specifies the scaling mode to use. |
boolean |
signalEndOfInputStream()
Signals end-of-stream on input.
|
boolean |
start()
After successfully configuring the component, call
start . |
boolean |
stop()
Finish the decode/encode session, note that the codec instance
remains active and ready to be
start() ed again. |
boolean isStarted()
boolean isReleased()
java.lang.Exception configureError()
java.lang.IllegalArgumentException
- if the surface has been released (or is invalid),
or the format is unacceptable (e.g. missing a mandatory key),
or the flags are not set properly
(e.g. missing CONFIGURE_FLAG_ENCODE for an encoder).java.lang.IllegalStateException
- if not in the Uninitialized state.MediaCodec.CryptoException
- upon DRM error.MediaCodec.CodecException
- upon codec error.boolean reset()
Call this if an unrecoverable
error has occured to reset the codec to its initial state after creation.
boolean release()
Make sure you call this when you're done to free up any opened component instance instead of relying on the garbage collector to do this for you at some point in the future.
boolean configure(android.media.MediaFormat format, android.view.Surface surface, android.media.MediaCrypto crypto, int flags)
format
- The format of the input data (decoder) or the desired
format of the output data (encoder). Passing null
as format
is equivalent to passing an
an empty mediaformat
.surface
- Specify a surface on which to render the output of this
decoder. Pass null
as surface
if the
codec does not generate raw video output (e.g. not a video
decoder) and/or if you want to configure the codec for
ByteBuffer
output.crypto
- Specify a crypto object to facilitate secure decryption
of the media data. Pass null
as crypto
for
non-secure codecs.flags
- Specify CONFIGURE_FLAG_ENCODE to configure the
component as an encoder.boolean configure(android.media.MediaFormat format, android.view.Surface surface, int flags, android.media.MediaDescrambler descrambler)
format
- The format of the input data (decoder) or the desired
format of the output data (encoder). Passing null
as format
is equivalent to passing an
an empty mediaformat
.surface
- Specify a surface on which to render the output of this
decoder. Pass null
as surface
if the
codec does not generate raw video output (e.g. not a video
decoder) and/or if you want to configure the codec for
ByteBuffer
output.flags
- Specify CONFIGURE_FLAG_ENCODE to configure the
component as an encoder.descrambler
- Specify a descrambler object to facilitate secure
descrambling of the media data, or null for non-secure codecs.boolean setOutputSurface(android.view.Surface surface)
This can only be used if the codec was configured with an output surface. The new output surface should have a compatible usage type to the original output surface. E.g. codecs may not support switching from a SurfaceTexture (GPU readable) output to ImageReader (software readable) output.
surface
- the output surface to use. It must not be null
.boolean setInputSurface(android.view.Surface surface)
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
and before start()
, in
lieu of createInputSurface()
.surface
- a persistent input surface created by createPersistentInputSurfaceandroid.view.Surface createInputSurface()
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
and before start()
.
The application is responsible for calling release() on the Surface when done.
The Surface must be rendered with a hardware-accelerated API, such as OpenGL ES.
Surface.lockCanvas(android.graphics.Rect)
may fail or produce
unexpected results.
boolean start()
start
.
Call start
also if the codec is configured in asynchronous mode,
and it has just been flushed, to resume requesting input buffers.
boolean stop()
start()
ed again.
To ensure that it is available to other client call release()
and don't just rely on garbage collection to eventually do this for you.boolean flush()
Upon return, all indices previously returned in calls to dequeueInputBuffer
and dequeueOutputBuffer
— or obtained
via Callback#onInputBufferAvailable onInputBufferAvailable or
Callback#onOutputBufferAvailable onOutputBufferAvailable callbacks — become
invalid, and all buffers are owned by the codec.
If the codec is configured in asynchronous mode, call start()
after flush
has returned to resume codec operations. The codec
will not request input buffers until this has happened.
Note, however, that there may still be outstanding onOutputBufferAvailable
callbacks that were not handled prior to calling flush
.
The indices returned via these callbacks also become invalid upon calling flush
and
should be discarded.
If the codec is configured in synchronous mode, codec will resume
automatically if it is configured with an input surface. Otherwise, it
will resume when dequeueInputBuffer
is called.
boolean queueInputBuffer(int index, int offset, int size, long presentationTimeUs, int flags)
getInputBuffer(int)
in response to a dequeueInputBuffer(long)
return value or a Callback#onInputBufferAvailable
callback.
Many decoders require the actual compressed data stream to be
preceded by "codec specific data", i.e. setup data used to initialize
the codec such as PPS/SPS in the case of AVC video or code tables
in the case of vorbis audio.
The class MediaExtractor
provides codec
specific data as part of
the returned track format in entries named "csd-0", "csd-1" ...
These buffers can be submitted directly after start()
or
flush()
by specifying the flag BUFFER_FLAG_CODEC_CONFIG
. However, if you configure the
codec with a MediaFormat
containing these keys, they
will be automatically submitted by MediaCodec directly after
start. Therefore, the use of BUFFER_FLAG_CODEC_CONFIG
flag is discouraged and is
recommended only for advanced users.
To indicate that this is the final piece of input data (or rather that no more input data follows unless the decoder is subsequently flushed) specify the flag BUFFER_FLAG_END_OF_STREAM.
Note: Prior to Build.VERSION_CODES.M
,
presentationTimeUs
was not propagated to the frame timestamp of (rendered)
Surface output buffers, and the resulting frame timestamp was undefined.
Use releaseOutputBuffer(int, long)
to ensure a specific frame timestamp is set.
Similarly, since frame timestamps can be used by the destination surface for rendering
synchronization, care must be taken to normalize presentationTimeUs so as to not be
mistaken for a system time. (See SurfaceView specifics).
index
- The index of a client-owned input buffer previously returned
in a call to dequeueInputBuffer(long)
.offset
- The byte offset into the input buffer at which the data starts.size
- The number of bytes of valid input data.presentationTimeUs
- The presentation timestamp in microseconds for this
buffer. This is normally the media time at which this
buffer should be presented (rendered). When using an output
surface, this will be propagated as the SurfaceTexture#getTimestamp
timestamp for the frame (after
conversion to nanoseconds).flags
- A bitmask of flags
BUFFER_FLAG_CODEC_CONFIG and BUFFER_FLAG_END_OF_STREAM.
While not prohibited, most codecs do not use the
BUFFER_FLAG_KEY_FRAME flag for input buffers.boolean queueSecureInputBuffer(int index, int offset, android.media.MediaCodec.CryptoInfo info, long presentationTimeUs, int flags)
queueInputBuffer
but submits a buffer that is
potentially encrypted.
Check out further notes at queueInputBuffer
.index
- The index of a client-owned input buffer previously returned
in a call to dequeueInputBuffer(long)
.offset
- The byte offset into the input buffer at which the data starts.info
- Metadata required to facilitate decryption, the object can be
reused immediately after this call returns.presentationTimeUs
- The presentation timestamp in microseconds for this
buffer. This is normally the media time at which this
buffer should be presented (rendered).flags
- A bitmask of flags
BUFFER_FLAG_CODEC_CONFIG and BUFFER_FLAG_END_OF_STREAM.
While not prohibited, most codecs do not use the
BUFFER_FLAG_KEY_FRAME flag for input buffers.int dequeueInputBuffer(long timeoutUs)
timeoutUs
- The timeout in microseconds, a negative timeout indicates "infinite".int dequeueOutputBuffer(android.media.MediaCodec.BufferInfo info, long timeoutUs)
info
- Will be filled with buffer meta data.timeoutUs
- The timeout in microseconds, a negative timeout indicates "infinite".boolean releaseOutputBuffer(int index, boolean render)
render
to true
will first send the buffer
to that output surface. The surface will release the buffer back to the codec once
it is no longer used/displayed.
Once an output buffer is released to the codec, it MUST NOT
be used until it is later retrieved by getOutputBuffer(int)
in response
to a dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
return value or a
Callback#onOutputBufferAvailable callback.
index
- The index of a client-owned output buffer previously returned
from a call to dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
.render
- If a valid surface was specified when configuring the codec,
passing true renders this output buffer to the surface.boolean releaseOutputBuffer(int index, long renderTimestampNs)
The timestamp may have special meaning depending on the destination surface.
SurfaceView specifics |
---|
If you render your buffer on a SurfaceView ,
you can use the timestamp to render the buffer at a specific time (at the
VSYNC at or after the buffer timestamp). For this to work, the timestamp
needs to be reasonably close to the current System.nanoTime() .
Currently, this is set as within one (1) second. A few notes:
|
Once an output buffer is released to the codec, it MUST NOT
be used until it is later retrieved by getOutputBuffer(int)
in response
to a dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
return value or a
Callback#onOutputBufferAvailable callback.
index
- The index of a client-owned output buffer previously returned
from a call to dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
.renderTimestampNs
- The timestamp to associate with this buffer when
it is sent to the Surface.boolean signalEndOfInputStream()
android.media.MediaFormat getOutputFormat()
android.media.MediaFormat getInputFormat()
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
returns successfully to
get the input format accepted by the codec. Do this to
determine what optional configuration parameters were
supported by the codec.android.media.MediaFormat getOutputFormat(int index)
index
- The index of a client-owned input buffer previously
returned from a call to dequeueInputBuffer(long)
.java.nio.ByteBuffer[] getInputBuffers()
Note: As of API 21, dequeued input buffers are
automatically cleared
.
Do not use this method if using an input surface.
java.nio.ByteBuffer[] getOutputBuffers()
Note: As of API 21, the position and limit of output buffers that are dequeued will be set to the valid data range.
Do not use this method if using an output surface.
java.nio.ByteBuffer getInputBuffer(int index)
cleared
, writable ByteBuffer
object for a dequeued input buffer index to contain the input data.
After calling this method any ByteBuffer or Image object previously returned for the same input index MUST no longer be used.
index
- The index of a client-owned input buffer previously
returned from a call to dequeueInputBuffer(long)
,
or received via an onInputBufferAvailable callback.android.media.Image getInputImage(int index)
After calling this method any ByteBuffer or Image object previously returned for the same input index MUST no longer be used.
index
- The index of a client-owned input buffer previously
returned from a call to dequeueInputBuffer(long)
,
or received via an onInputBufferAvailable callback.java.nio.ByteBuffer getOutputBuffer(int index)
After calling this method, any ByteBuffer or Image object previously returned for the same output index MUST no longer be used.
index
- The index of a client-owned output buffer previously
returned from a call to dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
,
or received via an onOutputBufferAvailable callback.android.media.Image getOutputImage(int index)
After calling this method, any ByteBuffer or Image object previously returned for the same output index MUST no longer be used.
index
- The index of a client-owned output buffer previously
returned from a call to dequeueOutputBuffer(android.media.MediaCodec.BufferInfo, long)
,
or received via an onOutputBufferAvailable callback.boolean setVideoScalingMode(int mode)
configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
specifies the scaling mode to use. The default is "scale to fit".
The scaling mode may be reset to the default each time an INFO_OUTPUT_BUFFERS_CHANGED event is received from the codec; therefore, the client must call this method after every buffer change event (and before the first output buffer is released for rendering) to ensure consistent scaling mode.
Since the INFO_OUTPUT_BUFFERS_CHANGED event is deprecated, this can also be done after each INFO_OUTPUT_FORMAT_CHANGED event.
java.lang.String getName()
android.os.PersistableBundle getMetrics()
Additional vendor-specific fields may also be present in the return value.
boolean setParameters(android.os.Bundle params)
params
- The bundle of parameters to set.boolean setCallback(android.media.MediaCodec.Callback cb, android.os.Handler handler)
If the client intends to use the component in asynchronous mode,
a valid callback should be provided before configure(android.media.MediaFormat, android.view.Surface, android.media.MediaCrypto, int)
is called.
When asynchronous callback is enabled, the client should not call
getInputBuffers()
, getOutputBuffers()
,
dequeueInputBuffer(long)
or dequeueOutputBuffer(BufferInfo, long).
Also, flush()
behaves differently in asynchronous mode. After calling
flush
, you must call start()
to "resume" receiving input buffers,
even if an input surface was created.
cb
- The callback that will run. Use null
to clear a previously
set callback (before configure
is called and run
in synchronous mode).handler
- Callbacks will happen on the handler's thread. If null
,
callbacks are done on the default thread (the caller's thread or the
main thread.)boolean setCallback(android.media.MediaCodec.Callback cb)
Same as setCallback(Callback, Handler) with handler set to null.
cb
- The callback that will run. Use null
to clear a previously
set callback (before configure
is called and run
in synchronous mode).boolean setOnFrameRenderedListener(android.media.MediaCodec.OnFrameRenderedListener listener, android.os.Handler handler)
This method can be called in any codec state, but will only have an effect in the Executing state for codecs that render buffers to the output surface.
Note: This callback is for informational purposes only: to get precise render timing samples, and can be significantly delayed and batched. Some frames may have been rendered even if there was no callback generated.
listener
- the callback that will be runhandler
- the callback will be run on the handler's thread. If null
,
the callback will be run on the default thread, which is the looper
from which the codec was created, or a new thread if there was none.android.media.MediaCodecInfo getCodecInfo()
java.lang.IllegalStateException
- if in the Released state.