HeifWriter

class HeifWriter : AutoCloseable

Writes one or more still images (of the same dimensions) into a heif file.

This class currently supports three input modes: INPUT_MODE_BUFFER, INPUT_MODE_SURFACE, or INPUT_MODE_BITMAP.

The general sequence (in pseudo-code) to write a heif file using this class is as follows:

1) Construct the writer:HeifWriter heifwriter = new HeifWriter(...);

2) If using surface input mode, obtain the input surface:Surface surface = heifwriter.getInputSurface();

3) Call start:heifwriter.start();

4) Depending on the chosen input mode, add one or more images using one of these methods:heifwriter.addYuvBuffer(...); Orheifwriter.addBitmap(...); Or render to the previously obtained surface

5) Call stop:heifwriter.stop(...);

6) Close the writer:heifwriter.close();

Please refer to the documentations on individual methods for the exact usage.

Summary

Nested types

Builder class for constructing a HeifWriter object from specified parameters.

Constants
const Int

The input mode where the client adds bitmaps.
const Int

The input mode where the client adds input buffers with YUV data.
const Int

The input mode where the client renders the images to an input Surface created by the writer.

Public functions
Unit
addBitmap(bitmap: Bitmap)

Add one bitmap to the heif file.
Unit
addExifData(imageIndex: Int, exifData: ByteArray, offset: Int, length: Int)

Add Exif data for the specified image.
Unit
addYuvBuffer(format: Int, data: ByteArray)

Add one YUV buffer to the heif file.
Surface

Retrieves the input surface for encoding.
Unit
setInputEndOfStreamTimestamp(timestampNs: @IntRange(from = 0) Long)

Set the timestamp (in nano seconds) of the last input frame to encode.
Unit

Start the heif writer.
Unit
stop(timeoutMs: @IntRange(from = 0) Long)

Stop the heif writer synchronously.

Inherited functions
From java.lang.AutoCloseable
abstract Unit

Constants

INPUT_MODE_BITMAP

Added in 1.0.0
const val INPUT_MODE_BITMAP = 2: Int

The input mode where the client adds bitmaps.

See also
addBitmap

INPUT_MODE_BUFFER

Added in 1.0.0
const val INPUT_MODE_BUFFER = 0: Int

The input mode where the client adds input buffers with YUV data.

See also
addYuvBuffer

INPUT_MODE_SURFACE

Added in 1.0.0
const val INPUT_MODE_SURFACE = 1: Int

The input mode where the client renders the images to an input Surface created by the writer. The input surface operates in single buffer mode. As a result, for use case where camera directly outputs to the input surface, this mode will not work because camera framework requires multiple buffers to operate in a pipeline fashion.

See also
getInputSurface

Public functions

addBitmap

Added in 1.0.0
fun addBitmap(bitmap: Bitmap): Unit

Add one bitmap to the heif file.

Parameters
bitmap: Bitmap

the bitmap to be added to the file.
Throws
java.lang.IllegalStateException

if not started or not configured to use bitmap input.

addExifData

Added in 1.0.0
fun addExifData(imageIndex: Int, exifData: ByteArray, offset: Int, length: Int): Unit

Add Exif data for the specified image. The data must be a valid Exif data block, starting with "Exif\0\0" followed by the TIFF header (See JEITA CP-3451C Section 4.5.2.)

Parameters
imageIndex: Int

index of the image, must be a valid index for the max number of image specified by setMaxImages.
exifData: ByteArray

byte buffer containing a Exif data block.
offset: Int

offset of the Exif data block within exifData.
length: Int

length of the Exif data block.

addYuvBuffer

Added in 1.0.0
fun addYuvBuffer(format: Int, data: ByteArray): Unit

Add one YUV buffer to the heif file.

Parameters
format: Int

The YUV format as defined in android.graphics.ImageFormat, currently only support YUV_420_888.
data: ByteArray

byte array containing the YUV data. If the format has more than one planes, they must be concatenated.
Throws
java.lang.IllegalStateException

if not started or not configured to use buffer input.

getInputSurface

Added in 1.0.0
fun getInputSurface(): Surface

Retrieves the input surface for encoding.

Returns
Surface

the input surface if configured to use surface input.
Throws
java.lang.IllegalStateException

if called after start or not configured to use surface input.

setInputEndOfStreamTimestamp

Added in 1.0.0
fun setInputEndOfStreamTimestamp(timestampNs: @IntRange(from = 0) Long): Unit

Set the timestamp (in nano seconds) of the last input frame to encode. This call is only valid for surface input. Client can use this to stop the heif writer earlier before the maximum number of images are written. If not called, the writer will only stop when the maximum number of images are written.

Parameters
timestampNs: @IntRange(from = 0) Long

timestamp (in nano seconds) of the last frame that will be written to the heif file. Frames with timestamps larger than the specified value will not be written. However, if a frame already started encoding when this is set, all tiles within that frame will be encoded.
Throws
java.lang.IllegalStateException

if not started or not configured to use surface input.

start

Added in 1.0.0
fun start(): Unit

Start the heif writer. Can only be called once.

Throws
java.lang.IllegalStateException

if called more than once.

stop

Added in 1.0.0
fun stop(timeoutMs: @IntRange(from = 0) Long): Unit

Stop the heif writer synchronously. Throws exception if the writer didn't finish writing successfully. Upon a success return: - For buffer and bitmap inputs, all images sent before stop will be written. - For surface input, images with timestamp on or before that specified in setInputEndOfStreamTimestamp will be written. In case where setInputEndOfStreamTimestamp was never called, stop will block until maximum number of images are received.

Parameters
timeoutMs: @IntRange(from = 0) Long

Maximum time (in microsec) to wait for the writer to complete, with zero indicating waiting indefinitely.
Throws
java.lang.Exception

if encountered error, in which case the output file may not be valid. In particular, TimeoutException is thrown when timed out, and is thrown when encountered codec error.
See also
setInputEndOfStreamTimestamp