# AvifWriter

Artifact: [androidx.heifwriter:heifwriter](https://developer.android.com/jetpack/androidx/releases/heifwriter) [View Source](https://cs.android.com/search?q=file:androidx/heifwriter/AvifWriter.java+class:androidx.heifwriter.AvifWriter) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

*** ** * ** ***


```
public final class AvifWriter implements AutoCloseable
```

<br />

*** ** * ** ***

This class writes one or more still images (of the same dimensions) into an AVIF file. It currently supports three input modes: `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_BUFFER()`, `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_SURFACE()`, or `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_BITMAP()`. The general sequence (in pseudo-code) to write a avif file using this class is as follows: 1) Construct the writer: AvifWriter avifwriter = new AvifWriter(...); 2) If using surface input mode, obtain the input surface: Surface surface = avifwriter.getInputSurface(); 3) Call start: avifwriter.start(); 4) Depending on the chosen input mode, add one or more images using one of these methods: avifwriter.addYuvBuffer(...); Or avifwriter.addBitmap(...); Or render to the previously obtained surface 5) Call stop: avifwriter.stop(...); 6) Close the writer: avifwriter.close(); Please refer to the documentations on individual methods for the exact usage.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/heifwriter/AvifWriter.Builder` Builder class for constructing a AvifWriter object from specified parameters. |

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_BITMAP() = 2` The input mode where the client adds bitmaps. |
| `static final int` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_BUFFER() = 0` The input mode where the client adds input buffers with YUV data. |
| `static final int` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#INPUT_MODE_SURFACE() = 1` The input mode where the client renders the images to an input Surface created by the writer. |

| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#addBitmap(android.graphics.Bitmap)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html bitmap)` Add one bitmap to the avif file. |
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#addExifData(int,byte[],int,int)( int imageIndex, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html byte[] exifData, int offset, int length )` Add Exif data for the specified image. |
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#addYuvBuffer(int,byte[])(int format, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html byte[] data)` Add one YUV buffer to the avif file. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/view/Surface.html` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#getInputSurface()()` Retrieves the input surface for encoding. |
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#setInputEndOfStreamTimestamp(long)(@https://developer.android.com/reference/androidx/annotation/IntRange(from = 0) long timestampNs)` Set the timestamp (in nano seconds) of the last input frame to encode. |
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#start()()` Start the avif writer. |
| `void` | `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#stop(long)(@https://developer.android.com/reference/androidx/annotation/IntRange(from = 0) long timeoutMs)` Stop the avif writer synchronously. |

| ### Inherited methods |
|---|
| From [java.lang.AutoCloseable](https://developer.android.com/reference/java/lang/AutoCloseable.html) |---|---| | `abstract void` | `https://developer.android.com/reference/java/lang/AutoCloseable.html#close()()` | |

## Constants

### INPUT_MODE_BITMAP

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public static final int INPUT_MODE_BITMAP = 2
```

The input mode where the client adds bitmaps.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#addBitmap(android.graphics.Bitmap)` |   |

### INPUT_MODE_BUFFER

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public static final int INPUT_MODE_BUFFER = 0
```

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

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#addYuvBuffer(int,byte[])` |   |

### INPUT_MODE_SURFACE

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public static final int INPUT_MODE_SURFACE = 1
```

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 |
|---|---|
| `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#getInputSurface()` |   |

## Public methods

### addBitmap

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void addBitmap(@NonNull Bitmap bitmap)
```

Add one bitmap to the avif file.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html bitmap` | the bitmap to be added to the file. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if not started or not configured to use bitmap input. |

### addExifData

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void addExifData(
    int imageIndex,
    @NonNull byte[] exifData,
    int offset,
    int length
)
```

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 |
|---|---|
| `int imageIndex` | index of the image, must be a valid index for the max number of image specified by `https://developer.android.com/reference/androidx/heifwriter/AvifWriter.Builder#setMaxImages(int)`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html byte[] exifData` | byte buffer containing a Exif data block. |
| `int offset` | offset of the Exif data block within exifData. |
| `int length` | length of the Exif data block. |

### addYuvBuffer

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void addYuvBuffer(int format, @NonNull byte[] data)
```

Add one YUV buffer to the avif file.

| Parameters |
|---|---|
| `int format` | The YUV format as defined in `https://developer.android.com/reference/android/graphics/ImageFormat.html`, currently only support YUV_420_888. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html byte[] data` | byte array containing the YUV data. If the format has more than one planes, they must be concatenated. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if not started or not configured to use buffer input. |

### getInputSurface

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public @NonNull Surface getInputSurface()
```

Retrieves the input surface for encoding.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/view/Surface.html` | the input surface if configured to use surface input. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if called after start or not configured to use surface input. |

### setInputEndOfStreamTimestamp

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs)
```

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 avif 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 0) long timestampNs` | timestamp (in nano seconds) of the last frame that will be written to the avif 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 |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if not started or not configured to use surface input. |

### start

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void start()
```

Start the avif writer. Can only be called once.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if called more than once. |

### stop

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/heifwriter#1.1.0)

```
public void stop(@IntRange(from = 0) long timeoutMs)
```

Stop the avif 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 `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#setInputEndOfStreamTimestamp(long)` will be written. In case where `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#setInputEndOfStreamTimestamp(long)` was never called, stop will block until maximum number of images are received.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 0) long timeoutMs` | Maximum time (in microsec) to wait for the writer to complete, with zero indicating waiting indefinitely. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/Exception.html` | if encountered error, in which case the output file may not be valid. In particular, `https://developer.android.com/reference/java/util/concurrent/TimeoutException.html` is thrown when timed out, and `https://developer.android.com/reference/android/media/MediaCodec.CodecException.html` is thrown when encountered codec error. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/heifwriter/AvifWriter#setInputEndOfStreamTimestamp(long)` |   |