Inconsistent Documentation for avformat_new_stream

[Philip Mann]

In https://ffmpeg.org/doxygen/4.1/group__lavf__core.html#gadcb0fd3e507d9b58fe78f61f8ad39827, the documentation for avformat_new_stream says about the AVCodec parameter:

"If non-NULL, the AVCodecContext corresponding to the new stream will be initialized to use this codec. This is needed for e.g. codec-specific defaults to be set, so codec should be provided if it is known."

However, the datatype of the 2nd parameter is AVCodec, not AVCodecContext. This seems to be a mistake in the documentation.

Also, in the detailed description for https://ffmpeg.org/doxygen/4.1/group__lavf__encoding.html, it says

"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 stream codec parameters information, such as the codec type, id and other parameters (e.g. width / height, the pixel or sample format, etc.) as known. The 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)."

This doesn't seem to make sense because the 2nd parameter to the function is just the AVCodec, not the AVCodecContext. it's unclear from the documentation what passing the codec to avformat_new_stream() really does.

[mkver]

There is no mistake in the documentation cited by you: avformat_new_stream() just uses this AVCodec to initialize the (now removed) public AVCodecContext ​here.

And your second quote does not apply to avformat_new_stream() at all, but rather says what the user should do after having called avformat_new_stream(). It also deals with AVCodecParameters and not with an AVCodecContext at all.