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
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 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 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