org.bytedeco.javacpp

Class avformat.AVDeviceInfoList

java.lang.Object

org.bytedeco.javacpp.Pointer

org.bytedeco.javacpp.avformat.AVDeviceInfoList

All Implemented Interfaces:

AutoCloseable

Enclosing class:

avformat

@Opaque
public static class avformat.AVDeviceInfoList
extends Pointer

\defgroup libavf libavformat I/O and Muxing/Demuxing Library Libavformat (lavf) is a library for dealing with various media container formats. Its main two purposes are demuxing - i.e. splitting a media file into component streams, and the reverse process of muxing - writing supplied data in a specified container format. It also has an \ref lavf_io "I/O module" which supports a number of protocols for accessing the data (e.g. file, tcp, http and others). Before using lavf, you need to call av_register_all() to register all compiled muxers, demuxers and protocols. Unless you are absolutely sure you won't use libavformat's network capabilities, you should also call avformat_network_init(). A supported input format is described by an AVInputFormat struct, conversely an output format is described by AVOutputFormat. You can iterate over all registered input/output formats using the av_iformat_next() / av_oformat_next() functions. The protocols layer is not part of the public API, so you can only get the names of supported protocols with the avio_enum_protocols() function. Main lavf structure used for both muxing and demuxing is AVFormatContext, which exports all information about the file being read or written. As with most Libavformat structures, its size is not part of public ABI, so it cannot be allocated on stack or directly with av_malloc(). To create an AVFormatContext, use avformat_alloc_context() (some functions, like avformat_open_input() might do that for you). Most importantly an AVFormatContext contains: \li the \ref AVFormatContext.iformat "input" or \ref AVFormatContext.oformat "output" format. It is either autodetected or set by user for input; always set by user for output. \li an \ref AVFormatContext.streams "array" of AVStreams, which describe all elementary streams stored in the file. AVStreams are typically referred to using their index in this array. \li an \ref AVFormatContext.pb "I/O context". It is either opened by lavf or set by user for input, always set by user for output (unless you are dealing with an AVFMT_NOFILE format). \section lavf_options Passing options to (de)muxers It is possible to configure lavf muxers and demuxers using the \ref avoptions mechanism. Generic (format-independent) libavformat options are provided by AVFormatContext, they can be examined from a user program by calling av_opt_next() / av_opt_find() on an allocated AVFormatContext (or its AVClass from avformat_get_class()). Private (format-specific) options are provided by AVFormatContext.priv_data if and only if AVInputFormat.priv_class / AVOutputFormat.priv_class of the corresponding format struct is non-NULL. Further options may be provided by the \ref AVFormatContext.pb "I/O context", if its AVClass is non-NULL, and the protocols layer. See the discussion on nesting in \ref avoptions documentation to learn how to access those. \section urls URL strings in libavformat are made of a scheme/protocol, a ':', and a scheme specific string. URLs without a scheme and ':' used for local files are supported but deprecated. "file:" should be used for local files. It is important that the scheme string is not taken from untrusted sources without checks. Note that some schemes/protocols are quite powerful, allowing access to both local and remote files, parts of them, concatenations of them, local audio and video devices and so on. \{ \defgroup lavf_decoding Demuxing \{ Demuxers read a media file and split it into chunks of data (\em packets). A \ref AVPacket "packet" contains one or more encoded frames which belongs to a single elementary stream. In the lavf API this process is represented by the avformat_open_input() function for opening a file, av_read_frame() for reading a single packet and finally avformat_close_input(), which does the cleanup. \section lavf_decoding_open Opening a media file The minimum information required to open a file is its URL, which is passed to avformat_open_input(), as in the following code:

 const char    *url = "file:in.mp3";
 AVFormatContext *s = NULL;
 int ret = avformat_open_input(&s, url, NULL, NULL);
 if (ret < 0)
     abort();
 

The above code attempts to allocate an AVFormatContext, open the specified file (autodetecting the format) and read the header, exporting the information stored there into s. Some formats do not have a header or do not store enough information there, so it is recommended that you call the avformat_find_stream_info() function which tries to read and decode a few frames to find missing information. In some cases you might want to preallocate an AVFormatContext yourself with avformat_alloc_context() and do some tweaking on it before passing it to avformat_open_input(). One such case is when you want to use custom functions for reading input data instead of lavf internal I/O layer. To do that, create your own AVIOContext with avio_alloc_context(), passing your reading callbacks to it. Then set the \em pb field of your AVFormatContext to newly created AVIOContext. Since the format of the opened file is in general not known until after avformat_open_input() has returned, it is not possible to set demuxer private options on a preallocated context. Instead, the options should be passed to avformat_open_input() wrapped in an AVDictionary:

 AVDictionary *options = NULL;
 av_dict_set(&options, "video_size", "640x480", 0);
 av_dict_set(&options, "pixel_format", "rgb24", 0);

 if (avformat_open_input(&s, url, NULL, &options) < 0)
     abort();
 av_dict_free(&options);
 

This code passes the private options 'video_size' and 'pixel_format' to the demuxer. They would be necessary for e.g. the rawvideo demuxer, since it cannot know how to interpret raw video data otherwise. If the format turns out to be something different than raw video, those options will not be recognized by the demuxer and therefore will not be applied. Such unrecognized options are then returned in the options dictionary (recognized options are consumed). The calling program can handle such unrecognized options as it wishes, e.g.

 AVDictionaryEntry *e;
 if (e = av_dict_get(options, "", NULL, AV_DICT_IGNORE_SUFFIX)) {
     fprintf(stderr, "Option %s not recognized by the demuxer.\n", e->key);
     abort();
 }
 

After you have finished reading the file, you must close it with avformat_close_input(). It will free everything associated with the file. \section lavf_decoding_read Reading from an opened file Reading data from an opened AVFormatContext is done by repeatedly calling av_read_frame() on it. Each call, if successful, will return an AVPacket containing encoded data for one AVStream, identified by AVPacket.stream_index. This packet may be passed straight into the libavcodec decoding functions avcodec_send_packet() or avcodec_decode_subtitle2() if the caller wishes to decode the data. AVPacket.pts, AVPacket.dts and AVPacket.duration timing information will be set if known. They may also be unset (i.e. AV_NOPTS_VALUE for pts/dts, 0 for duration) if the stream does not provide them. The timing information will be in AVStream.time_base units, i.e. it has to be multiplied by the timebase to convert them to seconds. If AVPacket.buf is set on the returned packet, then the packet is allocated dynamically and the user may keep it indefinitely. Otherwise, if AVPacket.buf is NULL, the packet data is backed by a static storage somewhere inside the demuxer and the packet is only valid until the next av_read_frame() call or closing the file. If the caller requires a longer lifetime, av_dup_packet() will make an av_malloc()ed copy of it. In both cases, the packet must be freed with av_packet_unref() when it is no longer needed. \section lavf_decoding_seek Seeking \} \defgroup lavf_encoding Muxing \{ Muxers take encoded data in the form of \ref AVPacket "AVPackets" and write it into files or other output bytestreams in the specified container format. The main API functions for muxing are avformat_write_header() for writing the file header, av_write_frame() / av_interleaved_write_frame() for writing the packets and av_write_trailer() for finalizing the file. At the beginning of the muxing process, the caller must first call avformat_alloc_context() to create a muxing context. The caller then sets up the muxer by filling the various fields in this context: - The \ref AVFormatContext.oformat "oformat" field must be set to select the muxer that will be used. - Unless the format is of the AVFMT_NOFILE type, the \ref AVFormatContext.pb "pb" field must be set to an opened IO context, either returned from avio_open2() or a custom one. - Unless the format is of the AVFMT_NOSTREAMS type, at least one stream must be created with the avformat_new_stream() function. The caller should fill the \ref AVStream.codecpar "stream codec parameters" information, such as the codec \ref AVCodecParameters.codec_type "type", \ref AVCodecParameters.codec_id "id" and other parameters (e.g. width / height, the pixel or sample format, etc.) as known. The \ref AVStream.time_base "stream timebase" should be set to the timebase that the caller desires to use for this stream (note that the timebase actually used by the muxer can be different, as will be described later). - It is advised to manually initialize only the relevant fields in AVCodecParameters, rather than using \ref avcodec_parameters_copy() during remuxing: there is no guarantee that the codec context values remain valid for both input and output format contexts. - The caller may fill in additional information, such as \ref AVFormatContext.metadata "global" or \ref AVStream.metadata "per-stream" metadata, \ref AVFormatContext.chapters "chapters", \ref AVFormatContext.programs "programs", etc. as described in the AVFormatContext documentation. Whether such information will actually be stored in the output depends on what the container format and the muxer support. When the muxing context is fully set up, the caller must call avformat_write_header() to initialize the muxer internals and write the file header. Whether anything actually is written to the IO context at this step depends on the muxer, but this function must always be called. Any muxer private options must be passed in the options parameter to this function. The data is then sent to the muxer by repeatedly calling av_write_frame() or av_interleaved_write_frame() (consult those functions' documentation for discussion on the difference between them; only one of them may be used with a single muxing context, they should not be mixed). Do note that the timing information on the packets sent to the muxer must be in the corresponding AVStream's timebase. That timebase is set by the muxer (in the avformat_write_header() step) and may be different from the timebase requested by the caller. Once all the data has been written, the caller must call av_write_trailer() to flush any buffered packets and finalize the output file, then close the IO context (if any) and finally free the muxing context with avformat_free_context(). \} \defgroup lavf_io I/O Read/Write \{ \section lavf_io_dirlist Directory listing The directory listing API makes it possible to list files on remote servers. Some of possible use cases: - an "open file" dialog to choose files from a remote location, - a recursive media finder providing a player with an ability to play all files from a given directory. \subsection lavf_io_dirlist_open Opening a directory At first, a directory needs to be opened by calling avio_open_dir() supplied with a URL and, optionally, ::AVDictionary containing protocol-specific parameters. The function returns zero or positive integer and allocates AVIODirContext on success.

 AVIODirContext *ctx = NULL;
 if (avio_open_dir(&ctx, "smb://example.com/some_dir", NULL) < 0) {
     fprintf(stderr, "Cannot open directory.\n");
     abort();
 }
 

This code tries to open a sample directory using smb protocol without any additional parameters. \subsection lavf_io_dirlist_read Reading entries Each directory's entry (i.e. file, another directory, anything else within ::AVIODirEntryType) is represented by AVIODirEntry. Reading consecutive entries from an opened AVIODirContext is done by repeatedly calling avio_read_dir() on it. Each call returns zero or positive integer if successful. Reading can be stopped right after the NULL entry has been read -- it means there are no entries left to be read. The following code reads all entries from a directory associated with ctx and prints their names to standard output.

 AVIODirEntry *entry = NULL;
 for (;;) {
     if (avio_read_dir(ctx, &entry) < 0) {
         fprintf(stderr, "Cannot list directory.\n");
         abort();
     }
     if (!entry)
         break;
     printf("%s\n", entry->name);
     avio_free_directory_entry(&entry);
 }
 

\} \defgroup lavf_codec Demuxers \{ \defgroup lavf_codec_native Native Demuxers \{ \} \defgroup lavf_codec_wrappers External library wrappers \{ \} \} \defgroup lavf_protos I/O Protocols \{ \} \defgroup lavf_internal Internal \{ \} \}

Nested Class Summary

Nested classes/interfaces inherited from class org.bytedeco.javacpp.Pointer

Pointer.CustomDeallocator, Pointer.Deallocator, Pointer.NativeDeallocator

Field Summary

Fields inherited from class org.bytedeco.javacpp.Pointer

address, capacity, limit, position

Constructor Summary

Constructors

Constructor and Description
AVDeviceInfoList() Empty constructor.
AVDeviceInfoList(Pointer p) Pointer cast constructor.

Method Summary

Methods inherited from class org.bytedeco.javacpp.Pointer

address, asBuffer, asByteBuffer, availablePhysicalBytes, calloc, capacity, capacity, close, deallocate, deallocate, deallocateReferences, deallocator, deallocator, equals, fill, formatBytes, free, hashCode, isNull, limit, limit, malloc, maxBytes, maxPhysicalBytes, memchr, memcmp, memcpy, memmove, memset, offsetof, parseBytes, physicalBytes, position, position, put, realloc, setNull, sizeof, toString, totalBytes, totalPhysicalBytes, withDeallocator, zero

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AVDeviceInfoList

public AVDeviceInfoList()

Empty constructor. Calls super((Pointer)null).

AVDeviceInfoList

public AVDeviceInfoList(Pointer p)

Pointer cast constructor. Invokes Pointer.Pointer(Pointer).