Source code for vcon.dialog

import requests
import hashlib
import base64
import os
import logging
import tempfile
import warnings
from datetime import datetime
from typing import Optional, List, Dict, Union, Any, Tuple
from dateutil import parser

logger = logging.getLogger(__name__)


def _import_ffmpeg():
    """Import ffmpeg-python for the video helpers, with a clear error if it is missing.

    The PyPI package named ``ffmpeg`` is an unrelated empty module; the video
    helpers need ``ffmpeg-python`` (the ``video`` extra) and the ffmpeg binary.
    """
    try:
        import ffmpeg
    except ImportError:
        ffmpeg = None
    if ffmpeg is None or not hasattr(ffmpeg, "probe"):
        raise ImportError(
            "The video helpers need ffmpeg-python: pip install 'vcon[video]', "
            "and the ffmpeg binary on PATH."
        )
    return ffmpeg

MIME_TYPES = [
    "text/plain",
    "audio/x-wav",
    "audio/wav",
    "audio/wave",
    "audio/mpeg",
    "audio/mp3",
    "audio/x-mp3",        # Specification required
    "audio/x-mp4",        # Specification required
    "audio/ogg",
    "audio/webm",
    "audio/x-m4a",
    "audio/aac",
    "video/x-mp4",
    "video/mp4",              # MP4 format
    "video/quicktime",        # MOV format
    "video/webm",             # WebM format
    "video/x-msvideo",        # AVI format
    "video/x-matroska",       # MKV format
    "video/mpeg",             # MPEG format
    "video/x-flv",            # FLV format
    "video/3gpp",             # 3GP format for mobile
    "video/x-m4v",            # M4V format (Apple variant)
    "multipart/mixed",
    "message/rfc822",
    "image/jpeg",
    "image/tiff",
    "application/pdf",  # Added for image data
    "application/json"  # Added for signaling data
]


# Content-hash format for external and inline media (draft-ietf-vcon-vcon-core-02).
# A content_hash is "<algorithm>-<base64url-of-digest>" with NO base64 padding,
# e.g. "sha512-GLy6IPa...". SHA-512 is the spec default; SHA-256 is still accepted
# so hashes emitted by older releases of this library continue to verify.
DEFAULT_CONTENT_HASH_ALGORITHM = "sha512"
SUPPORTED_CONTENT_HASH_ALGORITHMS = ("sha512", "sha256")


def _b64url_no_padding(data: bytes) -> str:
    """Base64url-encode ``data`` without trailing ``=`` padding (per the spec)."""
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")


[docs]def b64url_encode(data: bytes) -> str: """Base64url-encode ``data`` without padding. ``draft-ietf-vcon-vcon-core-04`` follows the JWS/RFC 7515 base64url convention: no trailing ``=`` padding. Use this (instead of calling ``base64.urlsafe_b64encode`` directly) whenever the library writes an inline ``base64url``-encoded dialog or attachment body. :param data: the raw bytes to encode :type data: bytes :return: the unpadded base64url-encoded string :rtype: str """ return _b64url_no_padding(data)
[docs]def b64url_decode(value: Union[str, bytes]) -> bytes: """Base64url-decode ``value``, accepting padded or unpadded input. ``base64.urlsafe_b64decode`` requires exact padding, which rejects the unpadded strings this library (and -04-conformant producers) now emits. This re-pads before decoding so both padded (legacy) and unpadded (spec-conformant) base64url bodies decode correctly. :param value: the base64url string (or bytes) to decode :type value: str or bytes :return: the decoded raw bytes :rtype: bytes """ if isinstance(value, str): value = value.encode("ascii") padded = value + b"=" * (-len(value) % 4) return base64.urlsafe_b64decode(padded)
[docs]def compute_content_hash( data: bytes, algorithm: str = DEFAULT_CONTENT_HASH_ALGORITHM ) -> str: """Compute a spec-formatted content hash for raw bytes. Returns ``"<algorithm>-<base64url-no-padding>"`` as required by draft-ietf-vcon-vcon-core-02 (e.g. ``"sha512-GLy6IPa..."``). :param data: the raw bytes to hash :type data: bytes :param algorithm: the hash algorithm to use (default: ``"sha512"``); ``"sha256"`` is also supported for backwards compatibility :type algorithm: str :return: the algorithm-prefixed, unpadded base64url content hash :rtype: str :raises ValueError: if ``algorithm`` is not a supported algorithm """ if algorithm not in SUPPORTED_CONTENT_HASH_ALGORITHMS: raise ValueError( f"Unsupported hash algorithm: {algorithm}. " f"Must be one of {SUPPORTED_CONTENT_HASH_ALGORITHMS}" ) digest = hashlib.new(algorithm, data).digest() return f"{algorithm}-{_b64url_no_padding(digest)}"
[docs]def parse_content_hash_algorithm(content_hash: str) -> Optional[str]: """Return the algorithm prefix of ``content_hash``. :param content_hash: a content hash value, optionally prefixed :type content_hash: str :return: ``"sha512"`` or ``"sha256"`` for a prefixed value, or ``None`` for a legacy unprefixed hash (which this library historically emitted as a padded base64url SHA-256 digest) :rtype: str or None """ for algorithm in SUPPORTED_CONTENT_HASH_ALGORITHMS: if content_hash.startswith(f"{algorithm}-"): return algorithm return None
_REMOVED_DIALOG_PARAMETERS = frozenset({ "originator", "party_history", "transfer", "transferee", "transferor", "transfer_target", "original", "consultation", "target_dialog", "recordings", "recording_set", }) def _reject_removed_parameters(kwargs: Dict[str, Any]) -> None: removed = sorted(set(kwargs) & _REMOVED_DIALOG_PARAMETERS) if removed: raise ValueError( f"Dialog parameter(s) {removed} were removed in vCon 0.5.0: " "originator belongs to the Session Object; party_history and the transfer " "parameters are Event Objects; recordings/recording_set are replaced by " "the Session Object." ) #: Accepted on input for backward compatibility, normalized to "recording". LEGACY_MEDIA_DIALOG_TYPES = ("audio", "video")
[docs]class Dialog: """ A class representing a dialog segment in a vCon conversation. A dialog represents a piece of conversation content, which can be: - text: Text-based communication (email, chat, SMS) - recording: Audio/video recording of the conversation - incomplete: Failed or incomplete conversation setup ``"audio"`` and ``"video"`` are accepted as deprecated aliases for ``recording``. Dialog content can be stored inline or referenced externally: - Inline: Content stored directly in the body field - External: Content referenced via URL with content_hash for integrity Media support: - Audio formats: WAV, MP3, MP4, OGG, WebM, AAC - Video formats: MP4, WebM, AVI, MKV, MOV, FLV, 3GP - Text formats: Plain text, multipart messages - Images: JPEG, TIFF, PDF Changes in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05): - ``parties`` lists the contributors only. The receivers are in the ``parties`` of the Session Object that references the dialog. - ``originator`` moved to the Session Object. - ``party_history`` was replaced by Event Objects (``vcon.event.Event``). - The ``transfer`` and ``recording-set`` dialog types were removed. Transfers are Events; a recording set is a Session. - An empty Dialog Object (``Dialog.placeholder()``, serialized as ``{}``) holds a position in the dialog array so that indices do not change. - ``redacted_segments`` was added. """ MIME_TYPES = [ "text/plain", "audio/x-wav", "audio/wav", "audio/wave", "audio/mpeg", "audio/mp3", "audio/x-mp3", # Specification required "audio/x-mp4", # Specification required "audio/ogg", "audio/webm", "audio/x-m4a", "audio/aac", "video/x-mp4", "video/ogg", "video/mp4", # MP4 format "video/quicktime", # MOV format "video/webm", # WebM format "video/x-msvideo", # AVI format "video/x-matroska", # MKV format "video/mpeg", # MPEG format "video/x-flv", # FLV format "video/3gpp", # 3GP format for mobile "video/x-m4v", # M4V format (Apple variant) "multipart/mixed", "message/rfc822", "image/jpeg", "image/tiff", "application/pdf", # Added for image data "application/json" # Added for signaling data ] # recording, text and incomplete are the core-05 types; audio and video # are deprecated aliases accepted on construction (they become recording). VALID_TYPES = [ "recording", "text", "incomplete", "audio", "video" ] # Valid disposition values for incomplete dialogs (from specification) VALID_DISPOSITIONS = [ "no-answer", "congestion", "failed", "busy", "hung-up", "voicemail-no-message" ]
[docs] def __init__( self, type: str, start: Union[datetime, str], parties: List[int], mediatype: Optional[str] = None, filename: Optional[str] = None, body: Optional[str] = None, encoding: Optional[str] = None, url: Optional[str] = None, disposition: Optional[str] = None, campaign: Optional[str] = None, interaction: Optional[str] = None, skill: Optional[str] = None, duration: Optional[float] = None, meta: Optional[dict] = None, # New parameters for signaling and extended functionality metadata: Optional[Dict[str, Any]] = None, signaling: Optional[Dict[str, Any]] = None, # New parameters for video metadata resolution: Optional[str] = None, frame_rate: Optional[float] = None, codec: Optional[str] = None, bitrate: Optional[int] = None, thumbnail: Optional[str] = None, # New required fields session_id: Optional[Union[Dict[str, str], List[Dict[str, str]]]] = None, content_hash: Optional[str] = None, # Additional fields from specification application: Optional[str] = None, message_id: Optional[str] = None, redacted_segments: Optional[List[Dict[str, Any]]] = None, **kwargs, ) -> None: """ Initialize a Dialog object. :param type: the type of the dialog (e.g. "text", "recording", "incomplete", "video") :type type: str :param start: the start time of the dialog :type start: datetime :param parties: the parties that contributed to the dialog (the receivers are in the Session Object) :type parties: List[int] :param mediatype: the MIME type of the dialog body :type mediatype: str or None :param filename: the filename of the dialog body :type filename: str or None :param body: the body of the dialog :type body: str or None :param encoding: the encoding of the dialog body :type encoding: str or None :param url: the URL of the dialog :type url: str or None :param disposition: the disposition of the dialog :type disposition: str or None :param campaign: the campaign that the dialog is associated with :type campaign: str or None :param interaction: the interaction that the dialog is associated with :type interaction: str or None :param skill: the skill that the dialog is associated with :type skill: str or None :param duration: the duration of the dialog :type duration: float or None :param meta: additional metadata for the dialog :type meta: dict or None :param metadata: structured metadata for the dialog (newer format) :type metadata: dict or None :param signaling: signaling-specific information :type signaling: dict or None :param resolution: video resolution (e.g., "1920x1080") :type resolution: str or None :param frame_rate: video frame rate in fps :type frame_rate: float or None :param codec: video codec (e.g., "H.264", "H.265") :type codec: str or None :param bitrate: video bitrate in kbps :type bitrate: int or None :param thumbnail: base64-encoded thumbnail image :type thumbnail: str or None :param session_id: Session identifier :type session_id: str or None :param content_hash: Hash for externally referenced files (replaces alg and signature) :type content_hash: str or None :param application: Application identifier for the dialog :type application: str or None :param message_id: Message identifier for email/text dialogs :type message_id: str or None :param redacted_segments: Redacted_segments Objects (start, end, optional parties) :type redacted_segments: list or None :param kwargs: Additional attributes to be set on the dialog """ _reject_removed_parameters(kwargs) # Validate dialog type if type not in self.VALID_TYPES: raise ValueError(f"Invalid dialog type: {type}. Must be one of {self.VALID_TYPES}") # Convert the start time to an ISO 8601 string from a datetime or a string if isinstance(start, datetime): start = start.isoformat() elif isinstance(start, str): start = parser.parse(start).isoformat() # Set attributes from named parameters that are not None for key, value in locals().items(): if value is not None and key not in ("self", "kwargs"): setattr(self, key, value) # Don't merge meta and metadata; keep both for backward compatibility # This ensures tests relying on dialog.meta will continue to work # while also allowing new code to use dialog.metadata if not hasattr(self, "metadata") and hasattr(self, "meta"): self.metadata = self.meta.copy() if self.meta else {} elif not hasattr(self, "meta") and hasattr(self, "metadata"): self.meta = self.metadata.copy() if self.metadata else {} elif not hasattr(self, "metadata") and not hasattr(self, "meta"): self.metadata = {} self.meta = {} # Set any additional kwargs as attributes for key, value in kwargs.items(): if value is not None: setattr(self, key, value) # "audio" and "video" are not core-05 Dialog types (4.5.1: recording, # text, incomplete or an extension value). They are accepted for # backward compatibility but never emitted: the Dialog is a recording, # and the media kind stays in mediatype. if type in LEGACY_MEDIA_DIALOG_TYPES: warnings.warn( f'Dialog type "{type}" is not a core-05 type; using "recording" ' "(the media kind is carried by mediatype)", DeprecationWarning, stacklevel=2, ) self.type = "recording" # Handling for specific dialog types if type == "incomplete" and not hasattr(self, "disposition"): raise ValueError("Dialog type 'incomplete' requires a disposition") # Validate disposition values for incomplete dialogs if (type == "incomplete" and hasattr(self, "disposition") and self.disposition): if self.disposition not in Dialog.VALID_DISPOSITIONS: raise ValueError( f"Invalid disposition '{self.disposition}'. " f"Must be one of: {Dialog.VALID_DISPOSITIONS}" ) # Auto-detect mediatype for video type if type == "video" and not hasattr(self, "mediatype"): # Try to infer mediatype from filename extension if available if hasattr(self, "filename") and self.filename: ext = self.filename.split('.')[-1].lower() if ext == "mp4": self.mediatype = "video/mp4" elif ext == "mov": self.mediatype = "video/quicktime" elif ext == "webm": self.mediatype = "video/webm" elif ext == "avi": self.mediatype = "video/x-msvideo" elif ext == "mkv": self.mediatype = "video/x-matroska" elif ext in ["mpg", "mpeg"]: self.mediatype = "video/mpeg" elif ext == "flv": self.mediatype = "video/x-flv" elif ext == "3gp": self.mediatype = "video/3gpp" elif ext == "m4v": self.mediatype = "video/x-m4v" else: # Default to MP4 if we can't determine from extension self.mediatype = "video/mp4" else: # Default mediatype for video self.mediatype = "video/mp4"
[docs] def to_dict(self): """ Returns a dictionary representation of the Dialog object. :return: a dictionary containing all non-None Dialog object attributes :rtype: dict """ # An empty placeholder Dialog Object serializes as {}. if getattr(self, "_placeholder", False): return {} # Check to see if the start time provided. If not, # set the start time to the current time if not hasattr(self, "start"): self.start = datetime.now().isoformat() # Get all attributes of the object dialog_dict = self.__dict__.copy() # meta/metadata are always initialized to {} for backward-compat # attribute access (see __init__); omit them from the serialized # form when still empty rather than emitting empty placeholders. return { k: v for k, v in dialog_dict.items() if v is not None and k != "_placeholder" and not (k in ("meta", "metadata") and v == {}) }
[docs] def add_external_data(self, url: str, filename: str, mediatype: str) -> None: """ Add external data to the dialog. :param url: the URL of the external data :type url: str :return: None :rtype: None """ self.url = url response = requests.get(url) if response.status_code == 200: self.mediatype = response.headers["Content-Type"] else: raise Exception(f"Failed to fetch external data: {response.status_code}") # Override the filename if provided, otherwise use the filename from the URL if filename: self.filename = filename else: # Extract filename from URL, removing any query parameters url_path = url.split("?")[0] self.filename = url_path.split("/")[-1] # Override the mediatype if provided, otherwise use the mediatype from the URL if mediatype: self.mediatype = mediatype # Calculate the content hash for external data raw_content = response.content self.content_hash = compute_content_hash(raw_content)
[docs] def add_inline_data(self, body: Union[str, bytes], filename: str, mediatype: str) -> None: """ Add inline data to the dialog. The Dialog is written with ``encoding: "base64url"``. Pass raw ``bytes`` and they are encoded; a ``str`` is taken to be base64url already. The ``content_hash`` is over the decoded content. :param body: the content as bytes, or as a base64url string :type body: bytes or str :param filename: the filename of the inline data :type filename: str :param mediatype: the mediatype of the inline data :type mediatype: str :return: None :rtype: None """ if isinstance(body, (bytes, bytearray)): body = b64url_encode(bytes(body)) self.body = body self.mediatype = mediatype self.filename = filename self.encoding = "base64url" self.content_hash = compute_content_hash(self._content_bytes())
[docs] def is_external_data(self) -> bool: """ Check if the dialog is an external data dialog. :return: True if the dialog is an external data dialog, False otherwise :rtype: bool """ return hasattr(self, "url")
[docs] def is_inline_data(self) -> bool: """ Check if the dialog is an inline data dialog. :return: True if the dialog is an inline data dialog, False otherwise :rtype: bool """ return not self.is_external_data()
[docs] def is_text(self) -> bool: """ Check if the dialog is a text dialog. :return: True if the dialog is a text dialog, False otherwise :rtype: bool """ return hasattr(self, "type") and self.type == "text"
[docs] def is_recording(self) -> bool: """ Check if the dialog is a recording dialog. :return: True if the dialog is a recording dialog, False otherwise :rtype: bool """ return hasattr(self, "type") and self.type == "recording"
[docs] def is_transfer(self) -> bool: """Deprecated: core-05 has no transfer Dialog type, so this is always False.""" warnings.warn( "Dialog.is_transfer() is deprecated: transfers are Events in core-05", DeprecationWarning, stacklevel=2 ) return False
[docs] def is_placeholder(self) -> bool: """ Check if the dialog is an empty placeholder Dialog Object (``{}``). """ return getattr(self, "_placeholder", False)
[docs] @classmethod def placeholder(cls) -> "Dialog": """ Create an empty Dialog Object (core-05 section 4.5.1). It has no parameters and no meaning; it holds a position in the dialog array so that the indices of the other Dialog Objects, and the references to them, do not change. It serializes as ``{}``. """ obj = cls.__new__(cls) obj._placeholder = True return obj
[docs] def is_incomplete(self) -> bool: """ Check if the dialog is an incomplete dialog. :return: True if the dialog is an incomplete dialog, False otherwise :rtype: bool """ return hasattr(self, "type") and self.type == "incomplete"
[docs] def is_audio(self) -> bool: """ Check if the dialog has audio content. :return: True if the dialog has audio content, False otherwise :rtype: bool """ return self.mediatype in [ "audio/x-wav", "audio/wav", "audio/wave", "audio/mpeg", "audio/mp3", "audio/ogg", "audio/webm", "audio/x-m4a", "audio/aac", ]
[docs] def is_video(self, content_type=None) -> bool: """ Check if the dialog has video content. Args: content_type: Optional content type to check. If None, use the dialog's mediatype. Returns: True if the content is a video format, False otherwise """ # Use provided content_type or dialog's mediatype check_type = content_type if content_type is not None else getattr(self, "mediatype", None) if not check_type: return False # Check if it's any of the supported video types video_types = [ "video/x-mp4", "video/ogg", "video/mp4", "video/quicktime", "video/webm", "video/x-msvideo", "video/x-matroska", "video/mpeg", "video/3gpp", "video/x-m4v", "video/x-flv" ] return check_type in video_types
[docs] def add_video_data(self, video_data, filename=None, mediatype=None, inline=True, metadata=None) -> None: """ Add video data to the dialog. Args: video_data: Binary video data or URL to video filename: Name of the video file mediatype: MIME type of the video, or auto-detected from filename if None inline: Whether to include the video as inline content (True) or external reference (False) metadata: Optional video metadata to include Returns: None """ # A video is a "recording" Dialog in core-05; mediatype says it is video. self.type = "recording" # Auto-detect mediatype from filename if not provided if not mediatype and filename: ext = filename.split('.')[-1].lower() ext_to_mediatype = { 'mp4': 'video/mp4', 'mov': 'video/quicktime', 'webm': 'video/webm', 'avi': 'video/x-msvideo', 'mkv': 'video/x-matroska', 'mpg': 'video/mpeg', 'mpeg': 'video/mpeg', 'flv': 'video/x-flv', 'ogg': 'video/ogg' } mediatype = ext_to_mediatype.get(ext, 'video/mp4') # Default to MP4 if unknown # Handle external vs inline data if inline: # For base64 encoding, convert to bytes if it's a string if isinstance(video_data, str) and not video_data.startswith('http'): video_data = video_data.encode() # Add inline data if isinstance(video_data, bytes): # Base64 encode the binary data encoded_data = b64url_encode(video_data) self.add_inline_data(encoded_data, filename, mediatype) else: # Assume it's already base64 encoded self.add_inline_data(video_data, filename, mediatype) else: # External data if isinstance(video_data, str) and (video_data.startswith('http://') or video_data.startswith('https://')): # It's a URL, use it directly self.add_external_data(video_data, filename, mediatype) else: # Cannot use non-URL as external data raise ValueError("External video references must be URLs") # Add metadata if provided if metadata: if not hasattr(self, "metadata"): self.metadata = {} if not hasattr(self, "meta"): self.meta = {} self.metadata["video"] = metadata self.meta["video"] = metadata
[docs] def extract_video_metadata(self, video_path=None) -> dict: """ Extract comprehensive metadata from video content using FFmpeg. Args: video_path: Optional path to video file. If None, uses the dialog's content. Returns: Dictionary containing detailed video metadata """ ffmpeg = _import_ffmpeg() # Create temporary file if working with inline data temp_file = None try: if video_path is None: if self.is_inline_data(): # Decode base64 content to temporary file temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") video_data = b64url_decode(self.body) temp_file.write(video_data) temp_file.close() video_path = temp_file.name elif self.is_external_data(): # Download from URL to temporary file temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") response = requests.get(self.url) temp_file.write(response.content) temp_file.close() video_path = temp_file.name else: raise ValueError("Cannot extract metadata: no video content available") # Use FFmpeg to extract metadata probe = ffmpeg.probe(video_path) # Find video stream video_stream = next((stream for stream in probe['streams'] if stream['codec_type'] == 'video'), None) if video_stream is None: raise ValueError("No video stream found in file") # Get format information format_info = probe.get('format', {}) # Extract comprehensive metadata metadata = { "duration": float(format_info.get("duration", 0)), "size_bytes": int(format_info.get("size", 0)), "bit_rate": int(format_info.get("bit_rate", 0)), "format": format_info.get("format_name", ""), # Video stream details "codec": video_stream.get("codec_name", ""), "codec_long_name": video_stream.get("codec_long_name", ""), "width": int(video_stream.get("width", 0)), "height": int(video_stream.get("height", 0)), "display_aspect_ratio": video_stream.get("display_aspect_ratio", ""), "pixel_format": video_stream.get("pix_fmt", ""), "profile": video_stream.get("profile", ""), "level": video_stream.get("level", -1), # Frame rate calculation "frame_rate": self._calculate_frame_rate(video_stream.get("avg_frame_rate", "0/1")), "total_frames": int(video_stream.get("nb_frames", 0)), # Color details if available "color_space": video_stream.get("color_space", ""), "color_transfer": video_stream.get("color_transfer", ""), "color_primaries": video_stream.get("color_primaries", ""), # Additional format-specific data "contains_audio": any(stream["codec_type"] == "audio" for stream in probe.get("streams", [])), "timestamp": datetime.now().isoformat() } return metadata except Exception as e: logger.error(f"Error extracting video metadata: {str(e)}") # Return minimal metadata on error return { "error": str(e), "format": self.get_video_format_from_mediatype(), "timestamp": datetime.now().isoformat() } finally: # Clean up temporary file if created if temp_file and os.path.exists(temp_file.name): os.unlink(temp_file.name)
def _calculate_frame_rate(self, frame_rate_str): """ Calculate numeric frame rate from FFmpeg frame rate string. Args: frame_rate_str: Frame rate as string in format "num/den" Returns: Frame rate as float """ try: if "/" in frame_rate_str: num, den = map(int, frame_rate_str.split("/")) if den == 0: return 0 return num / den else: return float(frame_rate_str) except (ValueError, ZeroDivisionError): return 0
[docs] def generate_video_thumbnail(self, timestamp=0.0, width=320, height=240, quality=90) -> bytes: """ Generate a high-quality thumbnail from the video at the specified timestamp. Args: timestamp: Time in seconds at which to extract the thumbnail frame width: Desired width of the thumbnail in pixels height: Desired height of the thumbnail in pixels quality: JPEG quality (1-100) Returns: Binary thumbnail data in JPEG format """ ffmpeg = _import_ffmpeg() if not self.is_video(): raise ValueError("Cannot generate thumbnail for non-video content") # Create temporary files temp_video = None temp_thumb = None try: # Setup source video file if self.is_inline_data(): temp_video = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") video_data = b64url_decode(self.body) temp_video.write(video_data) temp_video.close() video_path = temp_video.name elif self.is_external_data(): temp_video = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") response = requests.get(self.url) temp_video.write(response.content) temp_video.close() video_path = temp_video.name else: raise ValueError("Cannot generate thumbnail: no video content available") # Setup thumbnail output file temp_thumb = tempfile.NamedTemporaryFile(delete=False, suffix=".jpg") temp_thumb.close() # Get video duration to validate timestamp probe = ffmpeg.probe(video_path) duration = float(probe.get("format", {}).get("duration", 0)) # Ensure timestamp is within video duration validated_timestamp = min(max(0, timestamp), duration if duration > 0 else timestamp) # Generate thumbnail using FFmpeg ( ffmpeg .input(video_path, ss=validated_timestamp) .filter('scale', width, height) .output(temp_thumb.name, vframes=1, q=min(max(1, 31 - int(quality * 0.3)), 31)) .overwrite_output() .run(quiet=True) ) # Read the generated thumbnail with open(temp_thumb.name, "rb") as f: thumbnail_data = f.read() # Add thumbnail to metadata if not hasattr(self, "metadata"): self.metadata = {} if not hasattr(self, "meta"): self.meta = {} if "video" not in self.metadata: self.metadata["video"] = {} if "video" not in self.meta: self.meta["video"] = {} # Store thumbnail as base64 thumbnail_b64 = base64.b64encode(thumbnail_data).decode() self.metadata["video"]["thumbnail"] = { "data": thumbnail_b64, "content_type": "image/jpeg", "timestamp": validated_timestamp, "width": width, "height": height, "quality": quality } self.meta["video"]["thumbnail"] = self.metadata["video"]["thumbnail"] return thumbnail_data except Exception as e: logger.error(f"Error generating thumbnail: {str(e)}") raise finally: # Clean up temporary files if temp_video and os.path.exists(temp_video.name): os.unlink(temp_video.name) if temp_thumb and os.path.exists(temp_thumb.name): os.unlink(temp_thumb.name)
[docs] def add_streaming_video_reference(self, reference_id, mediatype, metadata=None) -> None: """ Add a reference to a streamable video. Args: reference_id: Unique identifier for the streamable video mediatype: MIME type of the video metadata: Optional video metadata Returns: None """ self.type = "recording" self.url = f"stream://{reference_id}" self.mediatype = mediatype # Add streaming-specific metadata if not hasattr(self, "metadata"): self.metadata = {} if not hasattr(self, "meta"): self.meta = {} self.metadata["streaming"] = { "reference_id": reference_id, "protocol": "stream" } self.meta["streaming"] = self.metadata["streaming"] # Add video metadata if provided if metadata: self.metadata["video"] = metadata self.meta["video"] = metadata
[docs] def get_video_format_from_mediatype(self, mediatype: Optional[str] = None) -> str: """ Get the video format name from a MIME type. Args: mediatype: MIME type of the video (default: this Dialog's mediatype) Returns: Format name (mp4, mov, etc.) """ mediatype_to_format = { 'video/mp4': 'mp4', 'video/x-mp4': 'mp4', 'video/quicktime': 'mov', 'video/webm': 'webm', 'video/x-msvideo': 'avi', 'video/x-matroska': 'mkv', 'video/mpeg': 'mpeg', 'video/x-flv': 'flv', 'video/ogg': 'ogg' } if mediatype is None: mediatype = getattr(self, "mediatype", None) return mediatype_to_format.get(mediatype, 'unknown')
[docs] def has_thumbnail(self) -> bool: """ Check if the video has a thumbnail. Returns: True if the video has a thumbnail, False otherwise """ if hasattr(self, "metadata") and "video" in self.metadata: return "thumbnail" in self.metadata["video"] return False
[docs] def add_video_with_optimal_storage(self, video_data, filename, mediatype=None, size_threshold_mb=10) -> None: """ Add video with the optimal storage method based on size. Args: video_data: Binary video data or URL filename: Name of the video file mediatype: MIME type of the video (optional) size_threshold_mb: Size threshold in MB for inline vs external storage Returns: None """ # Determine data size if it's binary data if isinstance(video_data, bytes): size_mb = len(video_data) / (1024 * 1024) # Use inline for small videos, external for larger ones if size_mb <= size_threshold_mb: self.add_video_data(video_data, filename, mediatype, inline=True) else: # For larger videos, we would typically upload to external storage # and then reference the URL, but this is a placeholder raise ValueError( f"Video size ({size_mb:.2f} MB) exceeds threshold ({size_threshold_mb} MB). " "Upload to external storage and use the URL instead." ) elif isinstance(video_data, str) and (video_data.startswith('http://') or video_data.startswith('https://')): # It's already a URL, use external reference self.add_video_data(video_data, filename, mediatype, inline=False) else: # Unknown format raise ValueError("video_data must be binary data or a URL")
[docs] def transcode_video(self, target_format, codec=None, bit_rate=None, width=None, height=None) -> None: """ Transcode the video to a different format or with different encoding parameters. Args: target_format: Target video format (mp4, webm, etc.) codec: Video codec to use (h264, vp9, etc.) bit_rate: Target bitrate in bits per second width: Target width (if resizing) height: Target height (if resizing) Returns: None - updates the dialog's content in place """ ffmpeg = _import_ffmpeg() if not self.is_video(): raise ValueError("Cannot transcode non-video content") # Setup temporary files temp_input = None temp_output = None try: # Get source video if self.is_inline_data(): temp_input = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") video_data = b64url_decode(self.body) temp_input.write(video_data) temp_input.close() input_path = temp_input.name elif self.is_external_data(): temp_input = tempfile.NamedTemporaryFile(delete=False, suffix=f".{self.get_video_format_from_mediatype()}") response = requests.get(self.url) temp_input.write(response.content) temp_input.close() input_path = temp_input.name else: raise ValueError("Cannot transcode: no video content available") original_format = self.get_video_format_from_mediatype() # Setup output file temp_output = tempfile.NamedTemporaryFile(delete=False, suffix=f".{target_format}") temp_output.close() # Setup FFmpeg conversion stream = ffmpeg.input(input_path) # Apply filters if needed if width is not None and height is not None: stream = stream.filter('scale', width, height) # Setup output parameters output_params = {} if codec: output_params['c:v'] = codec if bit_rate: output_params['b:v'] = bit_rate # Run transcoding ffmpeg.output(stream, temp_output.name, **output_params).overwrite_output().run(quiet=True) # Read the transcoded file with open(temp_output.name, "rb") as f: new_video_data = f.read() # Update the dialog with the new video ext_to_mediatype = { 'mp4': 'video/mp4', 'mov': 'video/quicktime', 'webm': 'video/webm', 'avi': 'video/x-msvideo', 'mkv': 'video/x-matroska', 'mpg': 'video/mpeg', 'mpeg': 'video/mpeg', 'flv': 'video/x-flv', 'ogg': 'video/ogg' } new_mediatype = ext_to_mediatype.get(target_format, f'video/{target_format}') new_filename = f"{os.path.splitext(self.filename)[0]}.{target_format}" if hasattr(self, "filename") else f"video.{target_format}" # Extract metadata from new video metadata = self.extract_video_metadata(temp_output.name) # Use add_video_data to replace current content (maintaining inline/external status) if self.is_inline_data(): encoded_data = b64url_encode(new_video_data) self.add_inline_data(encoded_data, new_filename, new_mediatype) # Update metadata to include transcoding info if not hasattr(self, "metadata"): self.metadata = {} if not hasattr(self, "meta"): self.meta = {} self.metadata["video"] = metadata self.metadata["video"]["transcoded"] = { "original_format": original_format, "target_format": target_format, "codec": codec, "bit_rate": bit_rate, "width": width, "height": height, "timestamp": datetime.now().isoformat() } self.meta["video"] = self.metadata["video"] elif self.is_external_data(): # For external data, we'd typically need to upload the file somewhere # This is just a placeholder - in a real implementation you'd upload the file # to an external storage service and update the URL logger.warning("Transcoding external video data not fully implemented") except Exception as e: logger.error(f"Error transcoding video: {str(e)}") raise finally: # Clean up temporary files if temp_input and os.path.exists(temp_input.name): os.unlink(temp_input.name) if temp_output and os.path.exists(temp_output.name): os.unlink(temp_output.name)
[docs] def is_email(self) -> bool: """ Check if the dialog is an email dialog. :return: True if the dialog is an email dialog, False otherwise :rtype: bool """ return hasattr(self, "mediatype") and self.mediatype == "message/rfc822"
[docs] def is_image(self) -> bool: """ Check if the dialog has image content. :return: True if the dialog has image content, False otherwise :rtype: bool """ return hasattr(self, "mediatype") and self.mediatype in [ "image/jpeg", "image/tiff", "application/pdf" ]
[docs] def is_pdf(self) -> bool: """ Check if the dialog has PDF content. :return: True if the dialog has PDF content, False otherwise :rtype: bool """ return hasattr(self, "mediatype") and self.mediatype == "application/pdf"
[docs] def add_image_data(self, image_path: str, mediatype: Optional[str] = None) -> None: """ Add image data to the dialog from a local file. :param image_path: Path to the image file :type image_path: str :param mediatype: MIME type of the image (optional, auto-detected if not provided) :type mediatype: str or None :return: None :rtype: None """ import os import mimetypes # Auto-detect mediatype if not provided if not mediatype: mediatype, _ = mimetypes.guess_type(image_path) if not mediatype or mediatype not in ["image/jpeg", "image/tiff", "application/pdf"]: raise ValueError(f"Unsupported image format. Must be JPEG, TIFF, or PDF.") # Read image data with open(image_path, 'rb') as f: image_data = f.read() # Extract filename from path filename = os.path.basename(image_path) # Add as inline data self.body = b64url_encode(image_data) self.mediatype = mediatype self.filename = filename self.encoding = "base64url" # Calculate hash for integrity validation self.content_hash = compute_content_hash(image_data) # Extract metadata if possible try: self.extract_image_metadata(image_data, mediatype) except Exception as e: # Log the error but don't fail if metadata extraction fails print(f"Warning: Could not extract image metadata: {str(e)}")
[docs] def extract_image_metadata(self, image_data: bytes, mediatype: str) -> None: """ Extract metadata from image data and add it to the dialog metadata. :param image_data: Raw image data :type image_data: bytes :param mediatype: MIME type of the image :type mediatype: str :return: None :rtype: None """ # Initialize metadata dict if it doesn't exist if not hasattr(self, "metadata") or not self.metadata: self.metadata = {} if "image" not in self.metadata: self.metadata["image"] = {} if mediatype == "application/pdf": # Extract PDF metadata try: import io from pypdf import PdfReader pdf = PdfReader(io.BytesIO(image_data)) self.metadata["image"]["pages"] = len(pdf.pages) if pdf.metadata: for key, value in pdf.metadata.items(): # Convert PDF metadata keys to standard format clean_key = key.lower().replace('/', '_') self.metadata["image"][clean_key] = str(value) except ImportError: # PyPDF not installed self.metadata["image"]["note"] = "Install PyPDF for enhanced PDF metadata" elif mediatype in ["image/jpeg", "image/tiff"]: # Extract image metadata try: import io from PIL import Image, ExifTags img = Image.open(io.BytesIO(image_data)) self.metadata["image"]["width"] = img.width self.metadata["image"]["height"] = img.height self.metadata["image"]["format"] = img.format # Extract EXIF data if available if hasattr(img, '_getexif') and img._getexif(): exif = { ExifTags.TAGS.get(tag, tag): value for tag, value in img._getexif().items() if tag in ExifTags.TAGS } # Add select EXIF data to metadata for key in ['DateTimeOriginal', 'Make', 'Model', 'Orientation']: if key in exif: self.metadata["image"][key.lower()] = str(exif[key]) except ImportError: # PIL not installed self.metadata["image"]["note"] = "Install Pillow for enhanced image metadata"
[docs] def generate_thumbnail(self, *args, **kwargs): """ Generate a thumbnail for an image or a video Dialog. For an image this calls :meth:`generate_image_thumbnail` (``max_size``, returns a base64url string or None). For a video it calls :meth:`generate_video_thumbnail` (``timestamp``, ``width``, ``height``, ``quality``; returns JPEG bytes). """ if self.is_video(): return self.generate_video_thumbnail(*args, **kwargs) return self.generate_image_thumbnail(*args, **kwargs)
[docs] def generate_image_thumbnail(self, max_size: Tuple[int, int] = (200, 200)) -> Optional[str]: """ Generate a thumbnail for the image and return it as a base64-encoded string. :param max_size: Maximum thumbnail dimensions (width, height) :type max_size: Tuple[int, int] :return: Base64-encoded thumbnail or None if generation fails :rtype: str or None """ if not self.is_image(): return None try: import io from PIL import Image # Get image data if hasattr(self, "body") and self.body: if self.encoding in ["base64url"]: image_data = b64url_decode(self.body) else: # If not base64 encoded, assume it's already raw data image_data = self.body.encode() if isinstance(self.body, str) else self.body else: # For external data if self.is_external_data(): response = requests.get(self.url) if response.status_code != 200: return None image_data = response.content else: return None # For PDFs, just return None as they require special handling if self.mediatype == "application/pdf": return None # Generate thumbnail img = Image.open(io.BytesIO(image_data)) img.thumbnail(max_size) # Save thumbnail to bytes thumb_io = io.BytesIO() img.save(thumb_io, format='JPEG') thumb_data = thumb_io.getvalue() # Return base64-encoded thumbnail return base64.b64encode(thumb_data).decode('utf-8') except Exception as e: print(f"Thumbnail generation failed: {str(e)}") return None
[docs] def is_external_data_changed(self) -> bool: """ Check to see if it's an external data dialog and verify the content hash. :return: True if the dialog is an external data dialog and the contents are valid, False otherwise :rtype: bool """ if not self.is_external_data(): return False try: if not hasattr(self, "content_hash"): return True response = requests.get(self.url) if response.status_code != 200: return True # Recompute using whatever algorithm the stored hash was emitted # with so both new (sha512-/sha256- prefixed) and legacy # (unprefixed, padded SHA-256) hashes verify correctly. algorithm = parse_content_hash_algorithm(self.content_hash) if algorithm is None: calculated = base64.urlsafe_b64encode( hashlib.sha256(response.content).digest() ).decode() else: calculated = compute_content_hash(response.content, algorithm) return calculated != self.content_hash except Exception as e: print(e) return True
# Convert the dialog from an external data dialog to an inline data dialog # by reading the contents from the URL then adding the contents to the body
[docs] def to_inline_data(self) -> None: """ Convert the dialog from an external data dialog to an inline data dialog by reading the contents from the URL then adding the contents to the body. :return: None :rtype: None """ # Read the contents from the URL response = requests.get(self.url) if response.status_code == 200: # For binary content, use response.content instead of response.text raw_content = response.content # Base64url encode the body self.body = b64url_encode(raw_content) self.mediatype = response.headers.get("Content-Type") else: raise Exception(f"Failed to fetch external data: {response.status_code}") # Calculate the content hash of the original binary content self.encoding = "base64url" self.content_hash = compute_content_hash(raw_content) # Set the filename if it doesn't exist if not hasattr(self, "filename"): self.filename = self.url.split("/")[-1] # Remove the url since this is now inline data delattr(self, "url")
[docs] def set_session_id(self, session_id: Union[Dict[str, str], List[Dict[str, str]]]) -> None: """ Set the session identifier for this dialog. :param session_id: The session identifier (SessionId or list of SessionId) :type session_id: dict or list :return: None :rtype: None """ self.session_id = session_id
[docs] def get_session_id(self) -> Optional[Union[Dict[str, str], List[Dict[str, str]]]]: """ Get the session identifier for this dialog. :return: The session identifier if set, None otherwise :rtype: str or None """ return getattr(self, "session_id", None)
[docs] def set_content_hash(self, content_hash: str) -> None: """ Set the content hash for externally referenced files. :param content_hash: The content hash value :type content_hash: str :return: None :rtype: None """ self.content_hash = content_hash
[docs] def get_content_hash(self) -> Optional[str]: """ Get the content hash for externally referenced files. :return: The content hash if set, None otherwise :rtype: str or None """ return getattr(self, "content_hash", None)
[docs] def calculate_content_hash( self, algorithm: str = DEFAULT_CONTENT_HASH_ALGORITHM ) -> str: """ Calculate the content hash for the dialog body. The hash covers the content itself: for a ``base64url`` body that is the decoded bytes, so the value matches a hash of the original file (what ``add_image_data()`` stores). Other bodies are hashed as UTF-8. The returned value is spec-formatted as ``"<algorithm>-<base64url>"`` with no base64 padding (draft-ietf-vcon-vcon-core-02), e.g. ``"sha512-GLy6IPa..."``. :param algorithm: The hash algorithm to use (default: ``"sha512"``). ``"sha256"`` is also supported for backwards compatibility. :type algorithm: str :return: The calculated hash value, prefixed with the algorithm name :rtype: str :raises ValueError: if there is no body to hash, or ``algorithm`` is not a supported algorithm """ if not hasattr(self, "body") or not self.body: raise ValueError("No body content available to hash") return compute_content_hash(self._content_bytes(), algorithm)
def _content_bytes(self) -> bytes: """The dialog content as bytes: decoded for base64url, else the body.""" body = self.body if getattr(self, "encoding", None) == "base64url" and isinstance(body, str): try: return b64url_decode(body) except (ValueError, TypeError): pass return body.encode() if isinstance(body, str) else body
[docs] def verify_content_hash( self, expected_hash: str, algorithm: Optional[str] = None ) -> bool: """ Verify the content hash against the expected value. The algorithm is inferred from the ``expected_hash`` prefix (``"sha512-"`` or ``"sha256-"``) so values produced by either this or older releases of the library verify correctly. A legacy unprefixed hash is treated as the padded base64url SHA-256 that vcon-lib emitted prior to the algorithm-prefixed format. :param expected_hash: The expected hash value :type expected_hash: str :param algorithm: Optional explicit algorithm override; when omitted the algorithm is taken from the ``expected_hash`` prefix :type algorithm: str or None :return: True if the hash matches, False otherwise :rtype: bool """ try: if not hasattr(self, "body") or not self.body: return False resolved = algorithm or parse_content_hash_algorithm(expected_hash) if resolved is None: # Legacy unprefixed hash: compare against the historical padded # base64url SHA-256 that older releases of this library emitted. body_bytes = ( self.body.encode() if isinstance(self.body, str) else self.body ) legacy = base64.urlsafe_b64encode( hashlib.sha256(body_bytes).digest() ).decode() return legacy == expected_hash if self.calculate_content_hash(resolved) == expected_hash: return True # 1.0.0 and earlier hashed a base64url body as its encoded text. body_bytes = self.body.encode() if isinstance(self.body, str) else self.body return compute_content_hash(body_bytes, resolved) == expected_hash except ValueError: return False