core: Gate experimental subtitle and video codec support.

Gate subtitle and video codec decoder traits behind experimental
feature flags as these will not be fully or correctly defined for
v0.6.0.

Author: pdeljanov

symphonia-core/Cargo.toml

@@ -27,6 +27,10 @@ opt-simd = [
     "opt-simd-neon",
 ]
 
+# Experimental features.
+exp-subtitle-codecs = []
+exp-video-codecs = []
+
 [dependencies]
 bitflags = "2.4.2"
 bytemuck = "1.7"

symphonia-core/src/codecs/registry.rs

@@ -12,9 +12,11 @@ use std::default::Default;
 use std::hash::Hash;
 
 use crate::codecs::audio::{AudioCodecId, AudioCodecParameters, AudioDecoder, AudioDecoderOptions};
+#[cfg(feature = "exp-subtitle-codecs")]
 use crate::codecs::subtitle::{
     SubtitleCodecId, SubtitleCodecParameters, SubtitleDecoder, SubtitleDecoderOptions,
 };
+#[cfg(feature = "exp-video-codecs")]
 use crate::codecs::video::{VideoCodecId, VideoCodecParameters, VideoDecoder, VideoDecoderOptions};
 use crate::codecs::CodecInfo;
 use crate::common::Tier;
@@ -42,6 +44,7 @@ pub trait RegisterableAudioDecoder: AudioDecoder {
 }
 
 /// Description of a supported video codec.
+#[cfg(feature = "exp-video-codecs")]
 #[derive(Copy, Clone)]
 pub struct SupportedVideoCodec {
     pub codec: VideoCodecId,
@@ -50,6 +53,7 @@ pub struct SupportedVideoCodec {
 
 /// To support registration in a codec registry, a `VideoDecoder` must implement the
 /// `RegisterableVideoDecoder` trait.
+#[cfg(feature = "exp-video-codecs")]
 pub trait RegisterableVideoDecoder: VideoDecoder {
     fn try_registry_new(
         params: &VideoCodecParameters,
@@ -63,6 +67,7 @@ pub trait RegisterableVideoDecoder: VideoDecoder {
 }
 
 /// Description of a supported subtitle codec.
+#[cfg(feature = "exp-subtitle-codecs")]
 #[derive(Copy, Clone)]
 pub struct SupportedSubtitleCodec {
     pub codec: SubtitleCodecId,
@@ -71,6 +76,7 @@ pub struct SupportedSubtitleCodec {
 
 /// To support registration in a codec registry, a `SubtitleDecoder` must implement the
 /// `RegisterableSubtitleDecoder` trait.
+#[cfg(feature = "exp-subtitle-codecs")]
 pub trait RegisterableSubtitleDecoded: SubtitleDecoder {
     fn try_registry_new(
         params: &SubtitleCodecParameters,
@@ -88,10 +94,12 @@ pub type AudioDecoderFactoryFn =
     fn(&AudioCodecParameters, &AudioDecoderOptions) -> Result<Box<dyn AudioDecoder>>;
 
 /// `VideoDecoder` factory function. Creates a boxed `VideoDecoder`.
+#[cfg(feature = "exp-video-codecs")]
 pub type VideoDecoderFactoryFn =
     fn(&VideoCodecParameters, &VideoDecoderOptions) -> Result<Box<dyn VideoDecoder>>;
 
 /// `SubtitleDecoder` factory function. Creates a boxed `SubtitleDecoder`.
+#[cfg(feature = "exp-subtitle-codecs")]
 pub type SubtitleDecoderFactoryFn =
     fn(&SubtitleCodecParameters, &SubtitleDecoderOptions) -> Result<Box<dyn SubtitleDecoder>>;
 
@@ -104,6 +112,7 @@ pub struct RegisteredAudioDecoder {
 }
 
 /// Registration details of a video decoder for a particular video codec.
+#[cfg(feature = "exp-video-codecs")]
 pub struct RegisteredVideoDecoder {
     /// Video codec details.
     pub codec: SupportedVideoCodec,
@@ -112,6 +121,7 @@ pub struct RegisteredVideoDecoder {
 }
 
 /// Registration details of a subtitle decoder for a particular subtitle codec.
+#[cfg(feature = "exp-subtitle-codecs")]
 pub struct RegisteredSubtitleDecoder {
     /// Subtitle codec details.
     pub codec: SupportedSubtitleCodec,
@@ -165,7 +175,9 @@ where
 #[derive(Default)]
 pub struct CodecRegistry {
     audio: InnerCodecRegistry<AudioCodecId, RegisteredAudioDecoder>,
+    #[cfg(feature = "exp-video-codecs")]
     video: InnerCodecRegistry<VideoCodecId, RegisteredVideoDecoder>,
+    #[cfg(feature = "exp-subtitle-codecs")]
     subtitle: InnerCodecRegistry<SubtitleCodecId, RegisteredSubtitleDecoder>,
 }
 
@@ -174,7 +186,9 @@ impl CodecRegistry {
     pub fn new() -> Self {
         CodecRegistry {
             audio: Default::default(),
+            #[cfg(feature = "exp-video-codecs")]
             video: Default::default(),
+            #[cfg(feature = "exp-subtitle-codecs")]
             subtitle: Default::default(),
         }
     }
@@ -197,12 +211,14 @@ impl CodecRegistry {
 
     /// Get the registration information of the most preferred video decoder for the specified
     /// video codec.
+    #[cfg(feature = "exp-video-codecs")]
     pub fn get_video_decoder(&self, id: VideoCodecId) -> Option<&RegisteredVideoDecoder> {
         self.video.get(&id)
     }
 
     /// Get the registration information of the video decoder at the specified tier for the
     /// specified video codec.
+    #[cfg(feature = "exp-video-codecs")]
     pub fn get_video_decoder_at_tier(
         &self,
         tier: Tier,
@@ -213,12 +229,14 @@ impl CodecRegistry {
 
     /// Get the registration information of the most preferred subtitle decoder for the specified
     /// subtitle codec.
+    #[cfg(feature = "exp-subtitle-codecs")]
     pub fn get_subtitle_decoder(&self, id: SubtitleCodecId) -> Option<&RegisteredSubtitleDecoder> {
         self.subtitle.get(&id)
     }
 
     /// Get the registration information of the subtitle decoder at the specified tier for the
     /// specified subtitle codec.
+    #[cfg(feature = "exp-subtitle-codecs")]
     pub fn get_subtitle_decoder_at_tier(
         &self,
         tier: Tier,
@@ -254,6 +272,7 @@ impl CodecRegistry {
     ///
     /// If a supported video codec was previously registered by another video decoder at the same
     /// tier, it will be replaced within the registry.
+    #[cfg(feature = "exp-video-codecs")]
     pub fn register_video_decoder<C: RegisterableVideoDecoder>(&mut self) {
         self.register_video_decoder_at_tier::<C>(Tier::Standard);
     }
@@ -262,6 +281,7 @@ impl CodecRegistry {
     ///
     /// If a supported codec was previously registered by another video decoder at the same tier, it
     /// will be replaced within the registry.
+    #[cfg(feature = "exp-video-codecs")]
     pub fn register_video_decoder_at_tier<C: RegisterableVideoDecoder>(&mut self, tier: Tier) {
         for codec in C::supported_codecs() {
             let reg = RegisteredVideoDecoder {
@@ -277,6 +297,7 @@ impl CodecRegistry {
     ///
     /// If a supported subtitle codec was previously registered by another subtitle decoder at the
     /// same tier, it will be replaced within the registry.
+    #[cfg(feature = "exp-subtitle-codecs")]
     pub fn register_subtitle_decoder<C: RegisterableSubtitleDecoded>(&mut self) {
         self.register_subtitle_decoder_at_tier::<C>(Tier::Standard);
     }
@@ -285,6 +306,7 @@ impl CodecRegistry {
     ///
     /// If a supported codec was previously registered by another subtitle decoder at the same tier,
     /// it will be replaced within the registry.
+    #[cfg(feature = "exp-subtitle-codecs")]
     pub fn register_subtitle_decoder_at_tier<C: RegisterableSubtitleDecoded>(
         &mut self,
         tier: Tier,
@@ -324,6 +346,7 @@ impl CodecRegistry {
     /// found, it will be instantiated with the provided video codec parameters and video decoder
     /// options. If a suitable decoder could not be found, or the decoder could not be instantiated,
     /// an error will be returned.
+    #[cfg(feature = "exp-video-codecs")]
     pub fn make_video_decoder(
         &self,
         params: &VideoCodecParameters,
@@ -343,6 +366,7 @@ impl CodecRegistry {
     /// is found, it will be instantiated with the provided subtitle codec parameters and subtitle
     /// decoder options. If a suitable decoder could not be found, or the decoder could not be
     /// instantiated, an error will be returned.
+    #[cfg(feature = "exp-subtitle-codecs")]
     pub fn make_subtitle_decoder(
         &self,
         params: &SubtitleCodecParameters,

symphonia-core/src/codecs/subtitle.rs

@@ -9,10 +9,14 @@
 
 use std::fmt;
 
+#[cfg(feature = "exp-subtitle-codecs")]
 use crate::codecs::CodecInfo;
 use crate::common::FourCc;
+#[cfg(feature = "exp-subtitle-codecs")]
 use crate::errors::Result;
+#[cfg(feature = "exp-subtitle-codecs")]
 use crate::formats::Packet;
+#[cfg(feature = "exp-subtitle-codecs")]
 use crate::subtitle::GenericSubtitleBufferRef;
 
 /// An `SubtitleCodecId` is a unique identifier used to identify a specific video codec.
@@ -84,13 +88,15 @@ impl SubtitleCodecParameters {
 }
 
 /// `SubtitleDecoderOptions` is a common set of options that all subtitle decoders use.
+#[cfg(feature = "exp-subtitle-codecs")]
 #[derive(Copy, Clone, Debug, Default)]
 pub struct SubtitleDecoderOptions {
     // None yet.
 }
 
 /// A `SubtitleDecoder` implements a subtitle codec's decode algorithm. It consumes `Packet`s and
 /// produces plain text or rendered subtitles.
+#[cfg(feature = "exp-subtitle-codecs")]
 pub trait SubtitleDecoder: Send + Sync {
     /// Reset the decoder.
     ///

symphonia-core/src/codecs/video.rs

@@ -9,7 +9,9 @@
 
 use std::fmt;
 
-use crate::codecs::{CodecInfo, CodecProfile};
+#[cfg(feature = "exp-video-codecs")]
+use crate::codecs::CodecInfo;
+use crate::codecs::CodecProfile;
 use crate::common::FourCc;
 
 /// An `VideoCodecId` is a unique identifier used to identify a specific video codec.
@@ -132,13 +134,15 @@ impl VideoCodecParameters {
 }
 
 /// `VideoDecoderOptions` is a common set of options that all subtitle decoders use.
+#[cfg(feature = "exp-video-codecs")]
 #[derive(Copy, Clone, Debug, Default)]
 pub struct VideoDecoderOptions {
     // None yet.
 }
 
 /// A `VideoDecoder` implements a video codec's decode algorithm. It consumes `Packet`s and
 /// produces video frames.
+#[cfg(feature = "exp-video-codecs")]
 pub trait VideoDecoder: Send + Sync {
     /// Reset the decoder.
     ///

symphonia-play/Cargo.toml

@@ -11,6 +11,13 @@ rust-version = "1.77"
 publish = false
 default-run = "symphonia-play"
 
+[features]
+exp-video-codecs = ["symphonia/exp-video-codecs"]
+exp-subtitle-codecs = ["symphonia/exp-subtitle-codecs"]
+
+# Enable experimental features since symphonia-play is a development tool.
+default = ["exp-subtitle-codecs", "exp-video-codecs"]
+
 [dependencies]
 clap = "3.1.0"
 lazy_static = "1.4.0"

symphonia-play/src/ui.rs

@@ -105,6 +105,7 @@ pub fn print_tracks(tracks: &[Track]) {
                         print_pair("Channel Map:", &channels, Bullet::None, 1);
                     }
                 }
+                #[cfg(feature = "exp-video-codecs")]
                 Some(CodecParameters::Video(params)) => {
                     let codec_info = reg.get_video_decoder(params.codec).map(|d| &d.codec.info);
 
@@ -130,6 +131,7 @@ pub fn print_tracks(tracks: &[Track]) {
                         print_pair("Height:", &height, Bullet::None, 1);
                     }
                 }
+                #[cfg(feature = "exp-subtitle-codecs")]
                 Some(CodecParameters::Subtitle(params)) => {
                     let codec_name = fmt_codec_name(
                         reg.get_subtitle_decoder(params.codec).map(|d| &d.codec.info),

symphonia/Cargo.toml

@@ -88,6 +88,10 @@ opt-simd = [
     "opt-simd-neon",
 ]
 
+# Experimental features.
+exp-subtitle-codecs = ["symphonia-core/exp-subtitle-codecs"]
+exp-video-codecs = ["symphonia-core/exp-video-codecs"]
+
 [dependencies]
 lazy_static = "1.4.0"
 

symphonia/src/lib.rs

@@ -88,6 +88,24 @@
 //!
 //! **Tip:** All SIMD optimizations can be enabled with the `opt-simd` feature flag.
 //!
+//! # Experimental Features
+//!
+//! Previews of experimental new features may be enabled by using feature flags. Experimental
+//! features should be used for development purposes only. Before using an experimental feature,
+//! please observe the warnings below. Never use experimental features in a production application.
+//!
+//! | Experimental Feature   | Feature Flag          |
+//! |------------------------|-----------------------|
+//! | Subtitle codec support | `exp-subtitle-codecs` |
+//! | Video codec support    | `exp-video-codecs`    |
+//!
+//! ## Warnings
+//!
+//! * SemVer compatibilty is **not** guaranteed. Be prepared for build failures.
+//! * Experimental features and their associated feature flags **may be removed at any time.**
+//! * Functionality **may change or break at any time.**
+//! * Again, **never** use in any production application.
+//!
 //! # Usage
 //!
 //! The following steps describe a basic usage of Symphonia: