Add release notes for 11.
authorAnton Khirnov <anton@khirnov.net>
Mon, 18 Aug 2014 18:04:47 +0000 (18:04 +0000)
committerDiego Biurrun <diego@biurrun.de>
Thu, 4 Sep 2014 14:14:27 +0000 (07:14 -0700)
Signed-off-by: Diego Biurrun <diego@biurrun.de>
doc/RELEASE_NOTES

index 478bc1d..bda4789 100644 (file)
@@ -1,51 +1,50 @@
 Release Notes
 =============
 
-* 10 "Eks"
+* 11 "One Louder"
 
 General notes
 -------------
 
-One of the main features of this release is the addition of reference-counted
-data buffers to Libav and their use in various structures. Specifically, the
-data buffers used by AVPacket and AVFrame can now be reference counted, which
-should allow to significantly simplify many use cases. In addition,
-reference-counted AVFrames can now be used in libavfilter, avoiding the need
-for a separate libavfilter-specific frame structure. Frames can now be passed
-straight from the decoders into filters or from filters to encoders.
+With this release we are trying to answer the numerous calls from our users for
+shorter development cycles. From now on we will aim for approximately two major
+releases per year.
 
-These additions made it necessary to bump the major versions of libavcodec,
-libavformat, libavdevice, libavfilter, and libavutil, which was accompanied by
-dropping some old deprecated APIs. These libraries are thus not ABI- or API-
-compatible with the previous release. All the other libraries (libavresample
-and libswscale) should be both ABI- and API-compatible.
+Libav 11 is API-, but not ABI-compatible with the previous major release. This
+means that the code using our libraries needs to be rebuilt, but no source
+changes should be required. Note however, that a number of old APIs remain
+deprecated and will be dropped in the near future. All users are strongly
+encouraged to update their code as soon as possible. The doc/APIchanges file in
+the Libav source tree and the migration guide on the wiki should help with
+migration to the new APIs. If those are not sufficient, do not hesitate to
+contact us on IRC or through the user mailing list.
 
-Another major point is the inclusion of the HEVC (AKA H.265, the successor of
-H.264) decoder in the main codebase. It was started in 2012 as a Libav Google
-Summer of Code project by Guillaume Martres and subsequently completed with
-the assistance of the OpenHEVC project and several Libav developers.
+One specific API issue in libavformat deserves mentioning here. When using
+libavcodec for decoding or encoding and libavformat for demuxing or muxing,
+the standard practice was to use the stream codec context (AVStream.codec) for
+actual decoding or encoding. There are multiple problems with this pattern
+(the main one is that the decoder/demuxer or encoder/muxer are not necessarily
+synchronized and may overwrite each other's state), so it is now strongly
+discouraged and will likely be deprecated in the future. Users should instead
+allocate a separate decoding or encoding context and populate it from the
+demuxing codec context (or the reverse for encoding) with the
+avcodec_copy_context() function.
 
-As usual, this release also contains support for other new formats, many smaller
-new features and countless bug fixes. We can highlight a native VP9 decoder,
-with encoding provided through libvpx, native decoders for WebP, JPEG 2000, and
-AIC, as well as improved WavPack support with encoding through libwavpack,
-support for more AAC flavors (LD - low delay, ELD - enhanced low delay), slice
-multithreading in libavfilter, or muxing chapters in ASF. Furthermore a few new
-filters have been introduced, namely compand, to change audio dynamics, framepack,
-to create stereoscopic videos, asetpts, to set audio pts, and interlace, to convert
-progressive video to interlaced. Finally there is more fine-grained detection of
-host and target libc, which should allow better portability to various cross
-compilation scenarios.
+The main highlights of this release include native Opus, VP7, OpenEXR, and On2
+AVC decoders, HEVC encoding through libx265, new APIs for exporting ReplayGain
+and display transformation metadata and countless bug fixes. A large effort was
+also expended on internal cleanups which are not very visible to our users,
+but should make the codebase cleaner, safer and easier to maintain and extend.
+One point worth mentioning is refactoring the large monolithic framework for
+architecture-specific codec optimizations into small blocks, which reduces the
+size of configurations that selectively enable or disable certain codecs.
 
-See the Changelog file for a fuller list of significant changes.
-
-Please note that our policy on bug reports has not changed. We still only accept
-bug reports against HEAD of the Libav trunk repository. If you are experiencing
-issues with any formally released version of Libav, please try a current version
-of the development code to check if the issue still exists. If it does, make
-your report against the development code following the usual bug reporting
-guidelines.
+The avserver streaming tool, which has not been maintained for many years and
+was mostly broken, was removed from the tree. It was decided that it is a
+significant maintenance burden and that we do our users no service by pretending
+to support it, while we in fact do not.
 
+See the Changelog file for a more extensive list of significant changes.
 
 API changes
 -----------
@@ -54,31 +53,23 @@ A number of additional APIs have been introduced and some existing functions
 have been deprecated and are scheduled for removal in the next release.
 Significant API changes include:
 
-[libavutil]
-+ added the reference-counted buffers API (buffers.h)
-+ moved the AVFrame struct to libavutil and added a new API for working with
-  reference-counted AVFrames (frame.h)
-
 [libavcodec]
-+ added an API for working with reference-counted AVPackets (av_packet_*)
-+- converted VDPAU to the hwaccel framework; the old way of using VDPAU is no
-   longer supported
-- old audio encoding and decoding APIs removed
-- old video encoding API removed
-- deprecated enum CodecID removed (enum AVCodecID should be used instead)
-- deprecated audio resampling API removed (libavresample should be used
-  instead)
++  Added the avcodec_copy_context() function that must from now on be used for
+   freeing codec contexts.
++- Added a new VDA hardware acceleration API, since the old one was broken and
+   not fixable in a compatible way. Deprecated the old VDA API.
+
+[libavformat]
++  Added support for exporting stream-global (as opposed to per-packet) side
+   data. This feature is now used by some demuxers to export ReplayGain or
+   display transformation matrix (aka rotation) or stereoscopic 3D mode.
++  Added an API for live metadata updates through event flags.
++- Changed the way to provide a hint about the desired timebase to muxers.
+   Previously it was done by setting AVStream.codec.time_base. Now callers
+   should set AVStream.time_base.
 
-[libavfilter]
-+- replaced AVFilterBufferRef with AVFrame; AVFilterBufferRef and everything
-   related to it still exists, but is deprecated
-+ converted all filters to use the AVOptions system for configuration, it is
-  now possible to query the supported options, their values and set them
-  directly with av_opt_*
-+ added a slice multithreading framework
-+- merged avfiltergraph.h to avfilter.h, using AVFilterGraph is now explicitly
-   mandatory (it was implicitly required even before); added new API for
-   allocating and initializing filters
+[libavresample]
++ Added an API for working with AVFrames.
 
 Please see the file doc/APIchanges for details along with similar
 programmer-centric information.