From 6059391e10244073c858cf9794b791293cbfcfca Mon Sep 17 00:00:00 2001
From: Philippe Normand <philn@igalia.com>
Date: Mon, 19 Feb 2024 12:25:01 +0000
Subject: [PATCH] protection: Document `original-media-type` caps field

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/6142>
---
 girs/Gst-1.0.gir                          | 11 ++++++++++-
 subprojects/gstreamer/gst/gstprotection.c |  9 +++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/girs/Gst-1.0.gir b/girs/Gst-1.0.gir
index 025ddd11f0..a3a23bca34 100644
--- a/girs/Gst-1.0.gir
+++ b/girs/Gst-1.0.gir
@@ -51884,7 +51884,16 @@ which is then encapsulated in a GstProtectionMeta object and attached to
 the corresponding output buffer using the gst_buffer_add_protection_meta()
 function. The information in this attached GstProtectionMeta would be
 used by a downstream decrypter element to recover the original unencrypted
-frame.</doc>
+frame.
+
+In addition to the #GstProtectionMeta demuxers signal encrypted streams with
+specific caps. The caps #GstStructure name will usually depend on the
+encryption scheme, for instance Common Encryption will be signaled with
+`application/x-cenc`. To prevent loss of information the media type of the
+decrypted stream will be stored in a `original-media-type` string field.
+Downstream elements can re-use that information, for instance decryptors can
+set their source pad caps according to the `original-media-type` received on
+their sink pad.</doc>
     </docsection>
     <docsection name="gststreams">
       <doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gststreams.c">A #GstStream is a high-level object defining a stream of data which is, or
diff --git a/subprojects/gstreamer/gst/gstprotection.c b/subprojects/gstreamer/gst/gstprotection.c
index 73deed811f..f174da6aeb 100644
--- a/subprojects/gstreamer/gst/gstprotection.c
+++ b/subprojects/gstreamer/gst/gstprotection.c
@@ -35,6 +35,15 @@
  * used by a downstream decrypter element to recover the original unencrypted
  * frame.
  *
+ * In addition to the #GstProtectionMeta demuxers signal encrypted streams with
+ * specific caps. The caps #GstStructure name will usually depend on the
+ * encryption scheme, for instance Common Encryption will be signaled with
+ * `application/x-cenc`. To prevent loss of information the media type of the
+ * decrypted stream will be stored in a `original-media-type` string field.
+ * Downstream elements can re-use that information, for instance decryptors can
+ * set their source pad caps according to the `original-media-type` received on
+ * their sink pad.
+ *
  * Since: 1.6
  */