diff --git a/pyogg/ogg_opus_writer.py b/pyogg/ogg_opus_writer.py index 547d0f5..accc3c9 100644 --- a/pyogg/ogg_opus_writer.py +++ b/pyogg/ogg_opus_writer.py @@ -4,6 +4,7 @@ import random import struct from typing import ( + List, Optional, Union, BinaryIO @@ -11,6 +12,7 @@ from . import ogg from . import opus +from . import __version__ from .opus_buffered_encoder import OpusBufferedEncoder #from .opus_encoder import OpusEncoder from .pyogg_error import PyOggError @@ -55,6 +57,9 @@ def __init__(self, # Create a new stream state with a random serial number self._stream_state = self._create_stream_state() + # Do not add any user comments to the generated stream + self._user_comments: List[str] = [] + # Create a packet (reused for each pass) self._ogg_packet = ogg.ogg_packet() self._packet_valid = False @@ -122,6 +127,22 @@ def write(self, pcm: memoryview) -> None: self._write_to_oggopus(pcm) + def add_user_comment(self, comment: str) -> None: + """Appends an user comment string to the generated Ogg Opus stream. + + Because such user comments are stored in Ogg Opus stream headers, calling + this method after they have been written (i.e., a call to the `write()` + method has been made) will have no effect. No user comments are written + by default. + + Comment strings are meant to be short, for the purposes of stream + identification only, in the `KEY=VALUE` format. The headers format provides + some leeway to allow longer and differently formatted comments, however. + For more information and a list of conventional comment string key values, + please check out .""" + self._user_comments.append(comment) + + def _write_to_oggopus(self, pcm: memoryview, flush: bool = False) -> None: assert self._encoder is not None @@ -318,15 +339,22 @@ def _make_comment_header(self): """ signature = b"OpusTags" - vendor_string = b"ENCODER=PyOgg" + vendor_string = f"PyOgg {__version__}".encode("utf-8") vendor_string_length = struct.pack("