add - doc - Added several format functions

---

We've added several format functions, such as checking for format support and encoding size.

---

Type: add
Breaking: False
Doc Required: True
Backport Required: False
Part: 1/1

BassBoom.Basolia/Format/ChannelCount.cs

@@ -0,0 +1,44 @@
+//
+// BassBoom  Copyright (C) 2023  Aptivi
+//
+// This file is part of BassBoom
+//
+// BassBoom is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// BassBoom is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY, without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+
+namespace BassBoom.Basolia.Format
+{
+    /// <summary>
+    /// Channel count
+    /// </summary>
+    public enum ChannelCount
+    {
+        /// <summary>
+        /// Unknown channel count
+        /// </summary>
+        Unknown = -1,
+        /// <summary>
+        /// Stereo
+        /// </summary>
+        Stereo = 1,
+        /// <summary>
+        /// Mono
+        /// </summary>
+        Mono,
+        /// <summary>
+        /// Both
+        /// </summary>
+        Both,
+    }
+}

BassBoom.Basolia/Format/FormatTools.cs

@@ -220,5 +220,126 @@ public static FormatInfo[] GetFormats(BasoliaMedia? basolia)
             // We're now entering the safe zone
             return [.. formats];
         }
+
+        /// <summary>
+        /// Is this format supported?
+        /// </summary>
+        /// <param name="basolia">Basolia instance that contains a valid handle</param>
+        /// <param name="rate">Rate</param>
+        /// <param name="encoding">Encoding</param>
+        /// <param name="channelCount">Mono, stereo, or both?</param>
+        public static bool IsFormatSupported(BasoliaMedia? basolia, long rate, int encoding, out ChannelCount channelCount)
+        {
+            InitBasolia.CheckInited();
+            if (basolia is null)
+                throw new BasoliaException("Basolia instance is not provided", mpg123_errors.MPG123_BAD_HANDLE);
+
+            // We're now entering the dangerous zone
+            unsafe
+            {
+                var handle = basolia._mpg123Handle;
+
+                // Check for support
+                var @delegate = MpgNative.GetDelegate<NativeOutput.mpg123_format_support>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format_support));
+                int channelCountInt = @delegate.Invoke(handle, rate, encoding);
+                channelCount = channelCountInt == 0 ? ChannelCount.Unknown : (ChannelCount)channelCountInt;
+            }
+
+            // We're now entering the safe zone
+            return channelCount != ChannelCount.Unknown;
+        }
+
+        /// <summary>
+        /// Is this format supported?
+        /// </summary>
+        /// <param name="encoding">Encoding</param>
+        public static int GetEncodingSize(int encoding)
+        {
+            InitBasolia.CheckInited();
+            int size = -1;
+
+            // We're now entering the dangerous zone
+            unsafe
+            {
+                // Check for support
+                var @delegate = MpgNative.GetDelegate<NativeOutput.mpg123_encsize>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_encsize));
+                size = @delegate.Invoke(encoding);
+            }
+
+            // We're now entering the safe zone
+            return size;
+        }
+
+        /// <summary>
+        /// Makes the underlying media handler accept no format
+        /// </summary>
+        /// <param name="basolia">Basolia instance that contains a valid handle</param>
+        public static void NoFormat(BasoliaMedia? basolia)
+        {
+            InitBasolia.CheckInited();
+            if (basolia is null)
+                throw new BasoliaException("Basolia instance is not provided", mpg123_errors.MPG123_BAD_HANDLE);
+
+            // We're now entering the dangerous zone
+            unsafe
+            {
+                var handle = basolia._mpg123Handle;
+
+                // Check for support
+                var @delegate = MpgNative.GetDelegate<NativeOutput.mpg123_format_none>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format_none));
+                int resetStatus = @delegate.Invoke(handle);
+                if (resetStatus != (int)mpg123_errors.MPG123_OK)
+                    throw new BasoliaException($"Can't reset output encoding", (mpg123_errors)resetStatus);
+            }
+        }
+
+        /// <summary>
+        /// Makes the underlying media handler accept all formats
+        /// </summary>
+        /// <param name="basolia">Basolia instance that contains a valid handle</param>
+        public static void AllFormats(BasoliaMedia? basolia)
+        {
+            InitBasolia.CheckInited();
+            if (basolia is null)
+                throw new BasoliaException("Basolia instance is not provided", mpg123_errors.MPG123_BAD_HANDLE);
+
+            // We're now entering the dangerous zone
+            unsafe
+            {
+                var handle = basolia._mpg123Handle;
+
+                // Check for support
+                var @delegate = MpgNative.GetDelegate<NativeOutput.mpg123_format_all>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format_all));
+                int resetStatus = @delegate.Invoke(handle);
+                if (resetStatus != (int)mpg123_errors.MPG123_OK)
+                    throw new BasoliaException($"Can't set output format", (mpg123_errors)resetStatus);
+            }
+        }
+
+        /// <summary>
+        /// Makes the underlying media handler use this specific format
+        /// </summary>
+        /// <param name="basolia">Basolia instance that contains a valid handle</param>
+        /// <param name="rate">Rate</param>
+        /// <param name="encoding">Encoding</param>
+        /// <param name="channels">Mono, stereo, or both?</param>
+        public static void UseFormat(BasoliaMedia? basolia, long rate, ChannelCount channels, int encoding)
+        {
+            InitBasolia.CheckInited();
+            if (basolia is null)
+                throw new BasoliaException("Basolia instance is not provided", mpg123_errors.MPG123_BAD_HANDLE);
+
+            // We're now entering the dangerous zone
+            unsafe
+            {
+                var handle = basolia._mpg123Handle;
+
+                // Check for support
+                var delegate2 = MpgNative.GetDelegate<NativeOutput.mpg123_format>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format));
+                int formatStatus = delegate2.Invoke(handle, rate, (int)channels, encoding);
+                if (formatStatus != (int)mpg123_errors.MPG123_OK)
+                    throw new BasoliaException($"Can't set output encoding to {rate}, {channels}, {encoding}", (mpg123_errors)formatStatus);
+            }
+        }
     }
 }

BassBoom.Basolia/Playback/PlaybackTools.cs

@@ -113,18 +113,12 @@ public static void Play(BasoliaMedia? basolia)
                 var handle = basolia._mpg123Handle;
                 var outHandle = basolia._out123Handle;
 
-                // First, get formats and reset them
+                // Reset the format. Orders here matter.
                 var (rate, channels, encoding) = FormatTools.GetFormatInfo(basolia);
-                var @delegate = MpgNative.GetDelegate<NativeOutput.mpg123_format_none>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format_none));
-                int resetStatus = @delegate.Invoke(handle);
-                if (resetStatus != (int)mpg123_errors.MPG123_OK)
-                    throw new BasoliaException($"Can't reset output encoding", (mpg123_errors)resetStatus);
+                FormatTools.NoFormat(basolia);
 
                 // Set the format
-                var delegate2 = MpgNative.GetDelegate<NativeOutput.mpg123_format>(MpgNative.libManagerMpg, nameof(NativeOutput.mpg123_format));
-                int formatStatus = delegate2.Invoke(handle, rate, channels, encoding);
-                if (formatStatus != (int)mpg123_errors.MPG123_OK)
-                    throw new BasoliaException($"Can't set output encoding", (mpg123_errors)formatStatus);
+                FormatTools.UseFormat(basolia, rate, (ChannelCount)channels, encoding);
                 Debug.WriteLine($"Format {rate}, {channels}, {encoding}");
 
                 // Try to open output to device

BassBoom.Cli/CliBase/Common.cs

@@ -149,9 +149,15 @@ internal static void ShowSpecs()
                 // Get the name and the description
                 string name = FormatTools.GetEncodingName(encoding);
                 string desc = FormatTools.GetEncodingDescription(encoding);
+                int size = FormatTools.GetEncodingSize(encoding);
 
-                encodingsBuilder.AppendLine($"  - {name} [{encoding}]: {desc}");
+                encodingsBuilder.AppendLine($"  - {name} [{encoding}, {size} bytes]: {desc}");
             }
+
+            var ratesBuilder = new StringBuilder();
+            int[] rates = FormatTools.GetRates();
+            foreach (int rate in rates)
+                ratesBuilder.AppendLine($"  - {rate} hertz");
 
             InfoBoxColor.WriteInfoBox(
                 $$"""
@@ -177,8 +183,7 @@ Encodings and Rates
                 Encodings:
                 {{encodingsBuilder}}
                 Rates:
-                  - {{string.Join("\n  - ", FormatTools.GetRates())}}
-
+                {{ratesBuilder}}
                 System specifications
                 =====================