public interface

Encoder

 androidx.camera.video.internal.encoder.Encoder

Subclasses:

EncoderImpl

Gradle dependencies

compile group: 'androidx.camera', name: 'camera-video', version: '1.2.0-alpha01'

  • groupId: androidx.camera
  • artifactId: camera-video
  • version: 1.2.0-alpha01

Artifact androidx.camera:camera-video:1.2.0-alpha01 it located at Google repository (https://maven.google.com/)

Overview

The encoder interface.

An encoder could be either a video encoder or an audio encoder. The interface defines the common APIs to communicate with an encoder.

Summary

Methods
public Encoder.EncoderInputgetInput()

Returns the encoder's input instance.

public voidpause()

Pauses the encoder.

public voidrelease()

Releases the encoder.

public voidrequestKeyFrame()

Request a key frame.

public voidsetEncoderCallback(EncoderCallback encoderCallback, java.util.concurrent.Executor executor)

Sets callback to encoder.

public voidstart()

Starts the encoder.

public voidstop()

Stops the encoder.

public voidstop(long expectedStopTimeUs)

Stops the encoder with an expected stop time.

Methods

public Encoder.EncoderInput getInput()

Returns the encoder's input instance.

public void start()

Starts the encoder.

If the encoder is not started yet, it will first trigger EncoderCallback.onEncodeStart(). Then continually invoke the EncoderCallback.onEncodedData(EncodedData) callback until the encoder is paused, stopped or released. It can call Encoder.pause() to pause the encoding after started. If the encoder is in paused state, then calling this method will resume the encoding.

public void stop()

Stops the encoder.

It will trigger EncoderCallback.onEncodeStop() after the last encoded data. It can call Encoder.start() to start again.

public void stop(long expectedStopTimeUs)

Stops the encoder with an expected stop time.

It will trigger EncoderCallback.onEncodeStop() after the last encoded data. It can call Encoder.start() to start again.

The encoder will try to provide the last EncodedData with a timestamp as close as to the given stop timestamp.

Parameters:

expectedStopTimeUs: The desired stop time.

public void pause()

Pauses the encoder.

Encoder.pause() only work between Encoder.start() and Encoder.stop(). Once the encoder is paused, it will drop the input data until Encoder.start() is invoked again.

public void release()

Releases the encoder.

Once the encoder is released, it cannot be used anymore. Any other method call after the encoder is released will get java.lang.IllegalStateException.

If this encoder takes Encoder.SurfaceInput, this method will release all the s updated via Encoder.SurfaceInput.setOnSurfaceUpdateListener(Executor, Encoder.SurfaceInput.OnSurfaceUpdateListener). So this method should only be called when the frame producer is finished with the surface which may be the current surface or one of the obsolete surfaces.

public void setEncoderCallback(EncoderCallback encoderCallback, java.util.concurrent.Executor executor)

Sets callback to encoder.

Parameters:

encoderCallback: the encoder callback
executor: the callback executor

public void requestKeyFrame()

Request a key frame.

Only take effect when the encoder is a video encoder and encoder is started.

Source

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.camera.video.internal.encoder;

import android.view.Surface;

import androidx.annotation.NonNull;
import androidx.annotation.RequiresApi;
import androidx.camera.video.internal.BufferProvider;

import java.util.concurrent.Executor;

/**
 * The encoder interface.
 *
 * <p>An encoder could be either a video encoder or an audio encoder. The interface defines the
 * common APIs to communicate with an encoder.
 */
@RequiresApi(21) // TODO(b/200306659): Remove and replace with annotation on package-info.java
public interface Encoder {

    /** Returns the encoder's input instance. */
    @NonNull
    EncoderInput getInput();

    /**
     * Starts the encoder.
     *
     * <p>If the encoder is not started yet, it will first trigger
     * {@link EncoderCallback#onEncodeStart}. Then continually invoke the
     * {@link EncoderCallback#onEncodedData} callback until the encoder is paused, stopped or
     * released. It can call {@link #pause} to pause the encoding after started. If the encoder is
     * in paused state, then calling this method will resume the encoding.
     */
    void start();

    /**
     * Stops the encoder.
     *
     * <p>It will trigger {@link EncoderCallback#onEncodeStop} after the last encoded data. It can
     * call {@link #start} to start again.
     */
    void stop();

    /**
     * Stops the encoder with an expected stop time.
     *
     * <p>It will trigger {@link EncoderCallback#onEncodeStop} after the last encoded data. It can
     * call {@link #start} to start again.
     *
     * <p>The encoder will try to provide the last {@link EncodedData} with a timestamp as close
     * as to the given stop timestamp.
     *
     * @param expectedStopTimeUs The desired stop time.
     */
    void stop(long expectedStopTimeUs);

    /**
     * Pauses the encoder.
     *
     * <p>{@link #pause} only work between {@link #start} and {@link #stop}.
     * Once the encoder is paused, it will drop the input data until {@link #start} is invoked
     * again.
     */
    void pause();

    /**
     * Releases the encoder.
     *
     * <p>Once the encoder is released, it cannot be used anymore. Any other method call after
     * the encoder is released will get {@link IllegalStateException}.
     *
     * <p>If this encoder takes {@link SurfaceInput}, this method will release all the
     * {@link Surface}s updated via {@link SurfaceInput#setOnSurfaceUpdateListener}. So this
     * method should only be called when the frame producer is finished with the surface which
     * may be the current surface or one of the obsolete surfaces.
     */
    void release();

    /**
     * Sets callback to encoder.
     *
     * @param encoderCallback the encoder callback
     * @param executor the callback executor
     */
    void setEncoderCallback(@NonNull EncoderCallback encoderCallback, @NonNull Executor executor);

    /**
     * Request a key frame.
     *
     * <p>Only take effect when the encoder is a video encoder and encoder is started.
     */
    void requestKeyFrame();

    /** The encoder's input. */
    interface EncoderInput {
    }

    /**
     * A SurfaceInput provides a {@link Surface} as the interface to receive video raw data.
     *
     * <p>SurfaceInput is only available for video encoder. It has to set
     * {@link #setOnSurfaceUpdateListener} to obtain the {@link Surface} update. A new surface
     * instance may be updated after there is already an updated surface. For Encoder, it is safe
     * and recommended to release the old surface by the surface receiver via
     * {@link Surface#release()} since the old surface is no longer used by Encoder. For the
     * latest surface, the receiver should rely on {@link Encoder#release()} to release it. After
     * {@link Encoder#release()} is called, all updated surfaces will be released.
     */
    interface SurfaceInput extends EncoderInput {

        void setOnSurfaceUpdateListener(@NonNull Executor executor,
                @NonNull OnSurfaceUpdateListener listener);

        /**
         * An interface for receiving the update event of the input {@link Surface} of the encoder.
         */
        interface OnSurfaceUpdateListener {
            /**
             * Notifies the surface is updated.
             *
             * @param surface the updated surface
             */
            void onSurfaceUpdate(@NonNull Surface surface);
        }
    }

    /**
     * A ByteBufferInput is a {@link BufferProvider} implementation and provides
     * {@link InputBuffer} to write input data to the encoder.
     *
     * @see BufferProvider
     * @see InputBuffer
     */
    interface ByteBufferInput extends EncoderInput, BufferProvider<InputBuffer> {
    }
}