release 1.41, api doc corrections for the IceCastClient

Author: irmen

README.md

@@ -347,7 +347,7 @@ stream_file() instead.
 
 *class*  ``CaptureDevice``
 
-``CaptureDevice  (self, input_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
+``CaptureDevice  (self, input_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend.CData, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
 > An audio device provided by miniaudio, for audio capture (recording).
 
 > *method*  ``close  (self) ``
@@ -388,7 +388,7 @@ callback generator as raw bytes. (it should already be started before)
 
 *class*  ``DuplexStream``
 
-``DuplexStream  (self, playback_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, playback_channels: int = 2, capture_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, capture_channels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, playback_device_id: Union[_cffi_backend._CDataBase, NoneType] = None, capture_device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
+``DuplexStream  (self, playback_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, playback_channels: int = 2, capture_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, capture_channels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, playback_device_id: Union[_cffi_backend.CData, NoneType] = None, capture_device_id: Union[_cffi_backend.CData, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
 > Joins a capture device and a playback device.
 
 > *method*  ``close  (self) ``
@@ -409,7 +409,19 @@ already be started before passing it in)
 ``IceCastClient  (self, url: str, update_stream_title: Callable[[ForwardRef('IceCastClient'), str], NoneType] = None) ``
 > A simple client for IceCast audio streams as miniaudio streamable source. If the stream has Icy
 Meta Data, the stream_title attribute will be updated with the actual title taken from the meta
-data. You can also provide a callback to be called when a new stream title is available.
+data. You can also provide a callback to be called when a new stream title is available. The
+downloading of the data from the internet is done in a background thread and it tries to keep a
+(small) buffer filled with available data to read.
+
+> *method*  ``close  (self) ``
+> > Stop the stream, aborting the background downloading.
+
+> *method*  ``read  (self, num_bytes: int) -> bytes``
+> > Read a chunk of data from the stream.
+
+> *method*  ``seek  (self, offset: int, origin: miniaudio.SeekOrigin) -> bool``
+> > Override this if the stream supports seeking. Note: seek support is sometimes not needed if you
+give the file type to a decoder upfront. You can ignore this method then.
 
 
 *class*  ``MiniaudioError``
@@ -420,7 +432,7 @@ data. You can also provide a callback to be called when a new stream title is av
 
 *class*  ``PlaybackDevice``
 
-``PlaybackDevice  (self, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend._CDataBase, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
+``PlaybackDevice  (self, output_format: miniaudio.SampleFormat = <SampleFormat.SIGNED16: 2>, nchannels: int = 2, sample_rate: int = 44100, buffersize_msec: int = 200, device_id: Union[_cffi_backend.CData, NoneType] = None, callback_periods: int = 0, backends: Union[List[miniaudio.Backend], NoneType] = None, thread_prio: miniaudio.ThreadPriority = <ThreadPriority.HIGHEST: 0>, app_name: str = '') ``
 > An audio device provided by miniaudio, for audio playback.
 
 > *method*  ``close  (self) ``
@@ -449,6 +461,16 @@ The generator should already be started before passing it in.
 > Base class for streams of audio data bytes. Can be used as a contextmanager, to properly call
 close().
 
+> *method*  ``close  (self) ``
+> > Override this to properly close the stream and free resources.
+
+> *method*  ``read  (self, num_bytes: int) -> Union[bytes, memoryview]``
+> > override this to provide data bytes to the consumer of the stream
+
+> *method*  ``seek  (self, offset: int, origin: miniaudio.SeekOrigin) -> bool``
+> > Override this if the stream supports seeking. Note: seek support is sometimes not needed if you
+give the file type to a decoder upfront. You can ignore this method then.
+
 
 *class*  ``WavFileReadStream``
 

miniaudio.py

@@ -5,7 +5,7 @@
 Software license: "MIT software license". See http://opensource.org/licenses/MIT
 """
 
-__version__ = "1.40"
+__version__ = "1.41"
 
 
 import abc
@@ -1042,14 +1042,19 @@ class StreamableSource(abc.ABC):
 
     @abc.abstractmethod
     def read(self, num_bytes: int) -> Union[bytes, memoryview]:
+        """override this to provide data bytes to the consumer of the stream"""
         pass
 
     def seek(self, offset: int, origin: SeekOrigin) -> bool:
-        # Note: seek support is usually not needed if you give the file type
-        # to the decoder upfront. You can ignore this method then.
+        """
+        Override this if the stream supports seeking.
+        Note: seek support is sometimes not needed if you give the file type
+        to a decoder upfront. You can ignore this method then.
+        """
         return False
 
     def close(self) -> None:
+        """Override this to properly close the stream and free resources."""
         pass
 
     def __enter__(self) -> "StreamableSource":
@@ -1065,6 +1070,8 @@ class IceCastClient(StreamableSource):
     If the stream has Icy Meta Data, the stream_title attribute will be updated
     with the actual title taken from the meta data.
     You can also provide a callback to be called when a new stream title is available.
+    The downloading of the data from the internet is done in a background thread
+    and it tries to keep a (small) buffer filled with available data to read.
     """
 
     BLOCK_SIZE = 8*1024
@@ -1087,7 +1094,7 @@ def __init__(self, url: str, update_stream_title: Callable[['IceCastClient', str
             self.station_name = result.headers["icy-name"]
             stream_format = result.headers["Content-Type"]
             self.audio_format = self.determine_audio_format(stream_format)
-        self._download_thread = threading.Thread(target=self.download_stream, daemon=True)
+        self._download_thread = threading.Thread(target=self._download_stream, daemon=True)
         self._download_thread.start()
 
     def determine_audio_format(self, stream_format: str) -> FileFormat:
@@ -1101,6 +1108,7 @@ def determine_audio_format(self, stream_format: str) -> FileFormat:
             return FileFormat.UNKNOWN
 
     def read(self, num_bytes: int) -> bytes:
+        """Read a chunk of data from the stream."""
         while len(self._buffer) < num_bytes:
             time.sleep(0.1)
         with self._buffer_lock:
@@ -1109,6 +1117,7 @@ def read(self, num_bytes: int) -> bytes:
             return chunk
 
     def close(self) -> None:
+        """Stop the stream, aborting the background downloading."""
         self._stop_stream = True
         self._download_thread.join()
 
@@ -1118,7 +1127,7 @@ def _readall(self, fileobject, size: int) -> bytes:
             b += fileobject.read(size)
         return b
 
-    def download_stream(self) -> None:
+    def _download_stream(self) -> None:
         req = urllib.request.Request(self.url, headers={"icy-metadata": "1"})
         with urllib.request.urlopen(req) as result:
             self.station_genre = result.headers["icy-genre"]
@@ -1144,7 +1153,7 @@ def download_stream(self) -> None:
                     meta_size = 16 * self._readall(result, 1)[0]
                     metadata = str(self._readall(result, meta_size).strip(b"\0"), "utf-8", errors="replace")
                     if metadata:
-                        search = re.search("StreamTItle='(.*?)'", metadata, re.IGNORECASE)
+                        search = re.search("StreamTitle='(.*?)'", metadata, re.IGNORECASE)
                         if search:
                             self.stream_title = search.group(1)
                             if self._update_title: