avutil/downmix_info: add a new API to propagate pre-made downmix matrixes

Useful for formats where they provide the downmix matrix in the bistream rather
than scale factors for channel groups.

Signed-off-by: James Almer <jamrial@gmail.com>

doc/APIchanges

@@ -2,6 +2,10 @@ The last version increases of all libraries were on 2026-06-23.
 
 API changes, most recent first:
 
+2026-07-11 - xxxxxxxxxxx - lavu 61.3.100 - downmix_info.h
+  Add AVDownmixMatrix, AVDownmixCoeff.
+  Add av_downmix_matrix_coeff(), av_downmix_matrix_alloc().
+
 2026-07-09 - xxxxxxxxxxx - lavc 63.6.100 - codec_id.h
   Add AV_CODEC_ID_ITUT_T35.
 

libavutil/downmix_info.c

@@ -20,6 +20,7 @@
 
 #include "downmix_info.h"
 #include "frame.h"
+#include "mem.h"
 
 AVDownmixInfo *av_downmix_info_update_side_data(AVFrame *frame)
 {
@@ -39,3 +40,46 @@ AVDownmixInfo *av_downmix_info_update_side_data(AVFrame *frame)
 
     return (AVDownmixInfo*)side_data->data;
 }
+
+#define MAX_CHANNELS 64
+
+static const int type_map[] = {
+    [AV_DOWNMIX_TYPE_UNKNOWN] = 0,
+    [AV_DOWNMIX_TYPE_LORO]    = 2,
+    [AV_DOWNMIX_TYPE_LTRT]    = 2,
+    [AV_DOWNMIX_TYPE_DPLII]   = 2,
+};
+
+AVDownmixMatrix *av_downmix_matrix_alloc(enum AVDownmixType type,
+                                         int in_ch_count, size_t *out_size)
+{
+    struct TestStruct {
+        AVDownmixMatrix p;
+        AVDownmixCoeff  b;
+    };
+    const size_t coeffs_offset = offsetof(struct TestStruct, b);
+    size_t size = coeffs_offset;
+    unsigned int nb_coeffs;
+    AVDownmixMatrix *dc;
+
+    if ((unsigned)type >= FF_ARRAY_ELEMS(type_map) ||
+        (unsigned)in_ch_count > MAX_CHANNELS)
+        return NULL;
+
+    nb_coeffs = type_map[type] * in_ch_count;
+    size += sizeof(AVDownmixCoeff) * nb_coeffs;
+
+    dc = av_mallocz(size);
+    if (!dc)
+        return NULL;
+
+    dc->downmix_type  = type;
+    dc->nb_coeffs     = nb_coeffs;
+    dc->in_ch_count   = in_ch_count;
+    dc->coeffs_offset = coeffs_offset;
+
+    if (out_size)
+        *out_size = size;
+
+    return dc;
+}

libavutil/downmix_info.h

@@ -21,6 +21,7 @@
 #ifndef AVUTIL_DOWNMIX_INFO_H
 #define AVUTIL_DOWNMIX_INFO_H
 
+#include "avassert.h"
 #include "frame.h"
 
 /**
@@ -104,6 +105,70 @@ typedef struct AVDownmixInfo {
  */
 AVDownmixInfo *av_downmix_info_update_side_data(AVFrame *frame);
 
+/**
+ * This structure describes optional metadata relevant to a downmix procedure
+ * in the form of a remixing matrix allocated as an array of AVDownmixCoeff.
+ * Must be allocated with @ref av_downmix_matrix_alloc.
+ *
+ * sizeof(AVDownmixMatrix) is not a part of the ABI and new fields may be
+ * added to it.
+ */
+typedef struct AVDownmixMatrix {
+    /**
+     * Type of downmix the coeffs will produce.
+     * Output channel count is derived from this value.
+     */
+    enum AVDownmixType downmix_type;
+
+    /**
+     * Input channel count.
+     */
+    int in_ch_count;
+
+    /**
+     * Amount of coefficients in the matrix.
+     */
+    unsigned int nb_coeffs;
+
+    /**
+     * Offset in bytes from the beginning of this structure at which the array
+     * of coefficients starts.
+     */
+    size_t coeffs_offset;
+} AVDownmixMatrix;
+
+/**
+ * Data type for storing coefficients, which are allocated as a part of
+ * AVDownmixMatrix and should be retrieved with @ref av_downmix_matrix_coeff.
+ */
+typedef double AVDownmixCoeff;
+
+/**
+ * Get a pointer to the coeff that represents the weight of input channel
+ * {@code in} in output channel {@code out}.
+ * in must be between 0 and @ref AVDownmixMatrix.in_ch_count "in_ch_count" - 1.
+ * out must be between 0 and the implicit output channel count from
+ * @ref AVDownmixMatrix.downmix_type "downmix_type" - 1.
+ */
+static av_always_inline AVDownmixCoeff*
+av_downmix_matrix_coeff(AVDownmixMatrix *dm, unsigned int out, unsigned int in)
+{
+    AVDownmixCoeff *coeff = (AVDownmixCoeff *)((uint8_t *)dm + dm->coeffs_offset);
+    return &coeff[in + dm->in_ch_count * out];
+}
+
+/**
+ * Allocates memory for AVDownmixMatrix of the given type, plus an array of
+ * {@code in_ch_count} times the implicit output channel count from {@code type}
+ * of AVDownmixCoeff and initializes the variables. Can be freed with a normal
+ * av_free() call.
+ *
+ * @param out_size if non-NULL, the size in bytes of the resulting data array is
+ * written here.
+ */
+AVDownmixMatrix *av_downmix_matrix_alloc(enum AVDownmixType type,
+                                         int in_ch_count, size_t *out_size);
+
 /**
  * @}
  */

libavutil/version.h

@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  61
-#define LIBAVUTIL_VERSION_MINOR   2
+#define LIBAVUTIL_VERSION_MINOR   3
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \