[Libav-user] AVStream::codec deprecated, but example uses it?

[Jason C]

In 3.1.5 it appears that AVStream::codec is deprecated:

    /**
     * @deprecated use the codecpar struct instead
     */
    attribute_deprecated
    AVCodecContext *codec;

But the examples linked to from the 3.1.x documentation
<https://ffmpeg.org/doxygen/3.1/examples.html> all use it, for example from
the demuxing/decoding example
<https://ffmpeg.org/doxygen/3.1/demuxing_decoding_8c-example.html>:

    /* find decoder for the stream */
    dec_ctx = st->codec;
    dec = avcodec_find_decoder(dec_ctx->codec_id);

So:

  - Either the example needs to be updated, or
  - AVStream::codec needs to not be deprecated any more, with the API
returned to the previously already-working-totally-fine-for-everything
form, or
  - avcodec_open2 needs to take an AVCodecParameters not an AVCodecContext,
or
  - The deprecated warning needs to be updated to make sense, because "use
the codecpar struct instead" isn't really actual information, it's mostly a
tantalizing breadcrumb to use when going back to scour all the disjoint
documentation.

As for what to actually do now... going from the mystery deprecation
message:

1. The docs for codecpar
<https://ffmpeg.org/doxygen/3.1/structAVStream.html#a12826d21779289356722971d362c583c>
are
completely blank, so that's a dead end.
2. The docs for AVCodecParameters
<https://ffmpeg.org/doxygen/3.1/structAVCodecParameters.html#details> don't
really contain any useful info, although they do mention some
avcodec_parameters_alloc() function, so let's follow that trail...
3. The docs for avcodec_parameters_alloc()
<https://ffmpeg.org/doxygen/3.1/group__lavc__core.html#ga647755ab2252e93221bb345f3d5e414f>
just state the obvious, so that's a dead end.
4. Uh... let's maybe try googling for AVStream codecpar?
  - Looked promising <https://ffmpeg.zeranoe.com/forum/viewtopic.php?t=3678>,
but nothing.
  - Everything else is pretty much just like that.
5. So... let's look at the avformat docs index
<https://ffmpeg.org/doxygen/3.1/avformat_8h.html> for something that takes
an AVCodecParameters: Nope, bad guess. Next guess:
6. The avcodec docs index <https://ffmpeg.org/doxygen/3.1/avcodec_8h.html>:
Well, there's this avcodec_parameters_to_context
<https://ffmpeg.org/doxygen/3.1/group__lavc__core.html#gac7b282f51540ca7a99416a3ba6ee0d16>
thing.
The docs say what it does but not why you'd want to use it. So in the
absence of any actual high level information about how the parts of these
libraries fit together to accomplish goals, I'm just going to guess that I
should take the AVStream::codecpar, convert it (or whatever it is that
function does) to an AVCodecContext (instead of just using AVStream::codec
to begin with), then pass that off to avcodec_open2 (at least, until that's
deprecated in favor of avcodec_open456 the next time the perpetually
unstable API gets a facelift), all the while wondering what I really just
gained by using codecpar instead of codec.

So:

- Is that what it meant by use codecpar instead? I'm really just guessing,
because none of it is *actually *documented.

- What did I just gain by switching over to codecpar from codec?

- That was way too much of a wild goose chase. Is there actual organized
documentation anywhere so I don't have to keep doing this?

Jason
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://ffmpeg.org/pipermail/libav-user/attachments/20161025/5d5b95de/attachment.html>