Class OpusEnc


  • public class OpusEnc
    extends java.lang.Object
    This is the documentation for the libopusenc C API.

    The libopusenc package provides a convenient high-level API for encoding Ogg Opus files.

    Organization

    The main API is divided into several sections:

    • encoding
    • comments
    • encoder_ctl
    • callbacks
    • error_codes

    Error Codes

    Many of the functions in this library return a negative error code when a function fails.

    • Method Detail

      • ope_comments_create

        public static long ope_comments_create()
        Create a new comments object.
        Returns:
        newly-created comments object
      • ope_comments_copy

        public static long ope_comments_copy​(long comments)
        Create a deep copy of a comments object.
        Parameters:
        comments - comments object to copy
        Returns:
        deep copy of input
      • ope_comments_destroy

        public static void ope_comments_destroy​(long comments)
        Destroys a comments object.
        Parameters:
        comments - comments object to destroy
      • nope_comments_add

        public static int nope_comments_add​(long comments,
                                            long tag,
                                            long val)
        Unsafe version of: comments_add
      • ope_comments_add

        public static int ope_comments_add​(long comments,
                                           java.nio.ByteBuffer tag,
                                           java.nio.ByteBuffer val)
        
        public static int ope_comments_add​(long comments,
                                           java.lang.CharSequence tag,
                                           java.lang.CharSequence val)
        
        Add a comment.
        Parameters:
        comments - where to add the comments
        tag - tag for the comment (must not contain = char)
        val - value for the tag
        Returns:
        error code
      • nope_comments_add_string

        public static int nope_comments_add_string​(long comments,
                                                   long tag_and_val)
        Unsafe version of: comments_add_string
      • ope_comments_add_string

        public static int ope_comments_add_string​(long comments,
                                                  java.nio.ByteBuffer tag_and_val)
        
        public static int ope_comments_add_string​(long comments,
                                                  java.lang.CharSequence tag_and_val)
        
        Add a comment as a single tag=value string.
        Parameters:
        comments - where to add the comments
        tag_and_val - string of the form tag=value (must contain = char)
        Returns:
        error code
      • nope_comments_add_picture

        public static int nope_comments_add_picture​(long comments,
                                                    long filename,
                                                    int picture_type,
                                                    long description)
        Unsafe version of: comments_add_picture
      • ope_comments_add_picture

        public static int ope_comments_add_picture​(long comments,
                                                   java.nio.ByteBuffer filename,
                                                   int picture_type,
                                                   @Nullable
                                                   java.nio.ByteBuffer description)
        
        public static int ope_comments_add_picture​(long comments,
                                                   java.lang.CharSequence filename,
                                                   int picture_type,
                                                   @Nullable
                                                   java.lang.CharSequence description)
        
        Add a picture from a file.
        Parameters:
        comments - where to add the comments
        filename - file name for the picture
        picture_type - type of picture (-1 for default)
        description - description (NULL means no comment)
        Returns:
        error code
      • nope_comments_add_picture_from_memory

        public static int nope_comments_add_picture_from_memory​(long comments,
                                                                long ptr,
                                                                long size,
                                                                int picture_type,
                                                                long description)
        Parameters:
        size - size of picture pointed to by ptr
      • ope_comments_add_picture_from_memory

        public static int ope_comments_add_picture_from_memory​(long comments,
                                                               java.nio.ByteBuffer ptr,
                                                               int picture_type,
                                                               @Nullable
                                                               java.nio.ByteBuffer description)
        
        public static int ope_comments_add_picture_from_memory​(long comments,
                                                               java.nio.ByteBuffer ptr,
                                                               int picture_type,
                                                               @Nullable
                                                               java.lang.CharSequence description)
        
        Add a picture already in memory.
        Parameters:
        comments - where to add the comments
        ptr - pointer to picture in memory
        picture_type - type of picture (-1 for default)
        description - description (NULL means no comment)
        Returns:
        error code
      • nope_encoder_create_file

        public static long nope_encoder_create_file​(long path,
                                                    long comments,
                                                    int rate,
                                                    int channels,
                                                    int family,
                                                    long error)
        Unsafe version of: encoder_create_file
      • ope_encoder_create_file

        public static long ope_encoder_create_file​(java.nio.ByteBuffer path,
                                                   long comments,
                                                   int rate,
                                                   int channels,
                                                   int family,
                                                   @Nullable
                                                   java.nio.IntBuffer error)
        
        public static long ope_encoder_create_file​(java.lang.CharSequence path,
                                                   long comments,
                                                   int rate,
                                                   int channels,
                                                   int family,
                                                   @Nullable
                                                   java.nio.IntBuffer error)
        
        Create a new OggOpus file.
        Parameters:
        path - path where to create the file
        comments - comments associated with the stream
        rate - input sampling rate (48 kHz is faster)
        channels - number of channels
        family - mapping family (0 for mono/stereo, 1 for surround)
        error - error code (NULL if no error is to be returned)
        Returns:
        newly-created encoder
      • nope_encoder_create_callbacks

        public static long nope_encoder_create_callbacks​(long callbacks,
                                                         long user_data,
                                                         long comments,
                                                         int rate,
                                                         int channels,
                                                         int family,
                                                         long error)
        Unsafe version of: encoder_create_callbacks
      • ope_encoder_create_callbacks

        public static long ope_encoder_create_callbacks​(OpusEncCallbacks callbacks,
                                                        long user_data,
                                                        long comments,
                                                        int rate,
                                                        int channels,
                                                        int family,
                                                        @Nullable
                                                        java.nio.IntBuffer error)
        Create a new OggOpus stream to be handled using callbacks
        Parameters:
        callbacks - callback functions
        user_data - pointer to be associated with the stream and passed to the callbacks
        comments - comments associated with the stream
        rate - input sampling rate (48 kHz is faster)
        channels - number of channels
        family - mapping family (0 for mono/stereo, 1 for surround)
        error - error code (NULL if no error is to be returned)
        Returns:
        newly-created encoder
      • nope_encoder_create_pull

        public static long nope_encoder_create_pull​(long comments,
                                                    int rate,
                                                    int channels,
                                                    int family,
                                                    long error)
        Unsafe version of: encoder_create_pull
      • ope_encoder_create_pull

        public static long ope_encoder_create_pull​(long comments,
                                                   int rate,
                                                   int channels,
                                                   int family,
                                                   @Nullable
                                                   java.nio.IntBuffer error)
        Create a new OggOpus stream to be used along with encoder_get_page. This is mostly useful for muxing with other streams.
        Parameters:
        comments - comments associated with the stream
        rate - input sampling rate (48 kHz is faster)
        channels - number of channels
        family - mapping family (0 for mono/stereo, 1 for surround)
        error - error code (NULL if no error is to be returned)
        Returns:
        newly-created encoder
      • nope_encoder_deferred_init_with_mapping

        public static int nope_encoder_deferred_init_with_mapping​(long enc,
                                                                  int family,
                                                                  int streams,
                                                                  int coupled_streams,
                                                                  long mapping)
      • ope_encoder_deferred_init_with_mapping

        public static int ope_encoder_deferred_init_with_mapping​(long enc,
                                                                 int family,
                                                                 int streams,
                                                                 int coupled_streams,
                                                                 java.nio.ByteBuffer mapping)
        Deferred initialization of the encoder to force an explicit channel mapping. This can be used to override the default channel coupling, but using it for regular surround will almost certainly lead to worse quality.
        Parameters:
        enc - encoder
        family - mapping family (0 for mono/stereo, 1 for surround)
        streams - total number of streams
        coupled_streams - number of coupled streams
        mapping - channel mapping
        Returns:
        error code
      • nope_encoder_write_float

        public static int nope_encoder_write_float​(long enc,
                                                   long pcm,
                                                   int samples_per_channel)
        Unsafe version of: encoder_write_float
      • ope_encoder_write_float

        public static int ope_encoder_write_float​(long enc,
                                                  java.nio.FloatBuffer pcm,
                                                  int samples_per_channel)
        Add/encode any number of float samples to the stream.
        Parameters:
        enc - encoder
        pcm - floating-point PCM values in the +/-1 range (interleaved if multiple channels)
        samples_per_channel - number of samples for each channel
        Returns:
        error code
      • nope_encoder_write

        public static int nope_encoder_write​(long enc,
                                             long pcm,
                                             int samples_per_channel)
        Unsafe version of: encoder_write
      • ope_encoder_write

        public static int ope_encoder_write​(long enc,
                                            java.nio.ShortBuffer pcm,
                                            int samples_per_channel)
        Add/encode any number of 16-bit linear samples to the stream.
        Parameters:
        enc - encoder
        pcm - linear 16-bit PCM values in the [-32768,32767] range (interleaved if multiple channels)
        samples_per_channel - number of samples for each channel
        Returns:
        error code
      • nope_encoder_get_page

        public static int nope_encoder_get_page​(long enc,
                                                long page,
                                                long len,
                                                int flush)
        Unsafe version of: encoder_get_page
      • ope_encoder_get_page

        public static boolean ope_encoder_get_page​(long enc,
                                                   org.lwjgl.PointerBuffer page,
                                                   java.nio.IntBuffer len,
                                                   boolean flush)
        Get the next page from the stream (only if using encoder_create_pull).
        Parameters:
        enc - encoder
        page - next available encoded page
        len - size (in bytes) of the page returned
        flush - if non-zero, forces a flush of the page (if any data available)
        Returns:
        1 if there is a page available, 0 if not
      • ope_encoder_drain

        public static int ope_encoder_drain​(long enc)
        Finalizes the stream, but does not deallocate the object.
        Parameters:
        enc - encoder
        Returns:
        error code
      • ope_encoder_destroy

        public static void ope_encoder_destroy​(long enc)
        Deallocates the obect. Make sure to encoder_drain first.
        Parameters:
        enc - encoder
      • ope_encoder_chain_current

        public static int ope_encoder_chain_current​(long enc,
                                                    long comments)
        Ends the stream and create a new stream within the same file.
        Parameters:
        enc - encoder
        comments - comments associated with the stream
        Returns:
        error code
      • nope_encoder_continue_new_file

        public static int nope_encoder_continue_new_file​(long enc,
                                                         long path,
                                                         long comments)
        Unsafe version of: encoder_continue_new_file
      • ope_encoder_continue_new_file

        public static int ope_encoder_continue_new_file​(long enc,
                                                        java.nio.ByteBuffer path,
                                                        long comments)
        
        public static int ope_encoder_continue_new_file​(long enc,
                                                        java.lang.CharSequence path,
                                                        long comments)
        
        Ends the stream and create a new file.
        Parameters:
        enc - encoder
        path - path where to write the new file
        comments - comments associated with the stream
        Returns:
        error code
      • ope_encoder_continue_new_callbacks

        public static int ope_encoder_continue_new_callbacks​(long enc,
                                                             long user_data,
                                                             long comments)
        Ends the stream and create a new file (callback-based).
        Parameters:
        enc - encoder
        user_data - pointer to be associated with the new stream and passed to the callbacks
        comments - comments associated with the stream
        Returns:
        error code
      • ope_encoder_flush_header

        public static int ope_encoder_flush_header​(long enc)
        Write out the header now rather than wait for audio to begin.
        Parameters:
        enc - encoder
        Returns:
        error code
      • nope_strerror

        public static long nope_strerror​(int error)
        Unsafe version of: strerror
      • ope_strerror

        @Nullable
        public static java.lang.String ope_strerror​(int error)
        Converts a libopusenc error code into a human readable string.
        Parameters:
        error - error number
        Returns:
        error string
      • nope_get_version_string

        public static long nope_get_version_string()
        Unsafe version of: get_version_string
      • ope_get_version_string

        @Nullable
        public static java.lang.String ope_get_version_string()
        Returns a string representing the version of libopusenc being used at run time.
        Returns:
        a string describing the version of this library
      • ope_get_abi_version

        public static int ope_get_abi_version()
        ABI version for this header. Can be used to check for features at run time.
        Returns:
        an integer representing the ABI version
      • ope_encoder_ctl

        public static int ope_encoder_ctl​(long enc,
                                          int request)
        
        public static int ope_encoder_ctl​(long enc,
                                          Opus.CTLRequest request)
        
        Sets encoder options.
        Parameters:
        enc - encoder
        request - use a request macro
        Returns:
        error code
      • OPE_SET_DECISION_DELAY_REQUEST

        public static Opus.CTLRequest OPE_SET_DECISION_DELAY_REQUEST​(int value)
      • OPE_GET_DECISION_DELAY_REQUEST

        public static Opus.CTLRequest OPE_GET_DECISION_DELAY_REQUEST​(java.nio.IntBuffer __result)
      • OPE_SET_MUXING_DELAY_REQUEST

        public static Opus.CTLRequest OPE_SET_MUXING_DELAY_REQUEST​(int value)
      • OPE_GET_MUXING_DELAY_REQUEST

        public static Opus.CTLRequest OPE_GET_MUXING_DELAY_REQUEST​(java.nio.IntBuffer __result)
      • OPE_SET_COMMENT_PADDING_REQUEST

        public static Opus.CTLRequest OPE_SET_COMMENT_PADDING_REQUEST​(int value)
      • OPE_GET_COMMENT_PADDING_REQUEST

        public static Opus.CTLRequest OPE_GET_COMMENT_PADDING_REQUEST​(java.nio.IntBuffer __result)
      • OPE_SET_SERIALNO_REQUEST

        public static Opus.CTLRequest OPE_SET_SERIALNO_REQUEST​(int value)
      • OPE_GET_SERIALNO_REQUEST

        public static Opus.CTLRequest OPE_GET_SERIALNO_REQUEST​(java.nio.IntBuffer __result)
      • OPE_SET_HEADER_GAIN_REQUEST

        public static Opus.CTLRequest OPE_SET_HEADER_GAIN_REQUEST​(int value)
      • OPE_GET_HEADER_GAIN_REQUEST

        public static Opus.CTLRequest OPE_GET_HEADER_GAIN_REQUEST​(java.nio.IntBuffer __result)
      • OPE_GET_NB_STREAMS_REQUEST

        public static Opus.CTLRequest OPE_GET_NB_STREAMS_REQUEST​(java.nio.IntBuffer __result)
      • OPE_GET_NB_COUPLED_STREAMS_REQUEST

        public static Opus.CTLRequest OPE_GET_NB_COUPLED_STREAMS_REQUEST​(java.nio.IntBuffer __result)