cuemsutils 0.1.0rc11__tar.gz → 0.1.0rc15__tar.gz

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cuemsutils
-Version: 0.1.0rc11
+Version: 0.1.0rc15
 Summary: Reusable classes and methods for CueMS system
 Project-URL: Documentation, https://stagesoft.github.io/cuems-utils/
 Project-URL: Issues, https://github.com/stagesoft/cuems-utils/issues

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/__init__.py

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2025-present Adrià (StageLab) <adria@stagelab.coop>
 #
 # SPDX-License-Identifier: GPL-3.0
-__version__ = "0.1.0rc11"
+# SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
+__version__ = "0.1.0rc15"

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/cues/AudioCue.py

@@ -6,7 +6,7 @@ from ..helpers import ensure_items
 from ..log import logged, Logger
 
 REQ_ITEMS = {
-    'master_vol': 1  # Default to full volume (0.0-1.0 range)
+    'master_vol': 100  # Default to full volume — 0-100 percent scale (cms:PercentType)
 }
 
 class AudioCue(MediaCue):

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/cues/FadeCue.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Stagelab Coop SCCL
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
+
 from enum import Enum
 
 from ..helpers import ensure_items, format_timecode
@@ -8,12 +12,22 @@ _ZERO_TC = CTimecode('00:00:00.000')
 
 
 class FadeCurveType(Enum):
-    """Enumeration of supported fade curve shapes."""
+    """Enumeration of supported fade curve shapes.
+
+    ``linear``, ``sigmoid``, ``ease_in`` and ``ease_out`` are the shapes
+    gradient-motiond's CurveFactory implements; the editor UI submits these.
+    ``exponential`` and ``logarithmic`` are legacy names kept so projects
+    authored by older editors still load — CurveFactory does NOT implement
+    them, and the frontend maps them onto ``ease_in``/``ease_out`` (the same
+    accelerating/decelerating shapes) on load, healing them on next save.
+    """
 
     linear = 'linear'
     exponential = 'exponential'
     logarithmic = 'logarithmic'
     sigmoid = 'sigmoid'
+    ease_in = 'ease_in'
+    ease_out = 'ease_out'
 
     def __str__(self):
         return self.value
@@ -125,7 +139,8 @@ class FadeCue(ActionCue):
 
         Args:
             curve_type (FadeCurveType | str): A FadeCurveType member or its
-                string value ('linear', 'exponential', 'logarithmic', 'sigmoid').
+                string value ('linear', 'sigmoid', 'ease_in', 'ease_out', or
+                the legacy 'exponential'/'logarithmic').
 
         Raises:
             ValueError: If curve_type is not a recognised value.

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/cues/MediaCue.py

@@ -1,3 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Stagelab Coop SCCL
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
 from typing import Tuple
 
 from .Cue import Cue
@@ -237,6 +240,93 @@ class Media(CuemsDict):
 
     regions: list[Region] = property(get_regions, set_regions)
 
+    # --- Stored size of the media file (869fat84r) --------------------------
+    #
+    # ``pixel_width`` / ``pixel_height`` are the original size of the file's
+    # first video stream, as ffprobe reports it, and ``file_size`` is the
+    # file's size in bytes when they were measured. ``file_md5`` (below)
+    # identifies the file itself. The editor stores them at
+    # upload so the engine does not have to probe the file when it arms a
+    # cue; ``file_size`` lets the engine notice a file replaced under the
+    # same name. All three are optional: absent means unknown.
+    #
+    # Parsing a project never calls these setters (the parsers assign keys
+    # raw), so the schema and MediaXmlBuilder, not these, guard what is read
+    # from and written to a file.
+
+    def _get_optional(self, key):
+        return self.get(key)
+
+    def _set_positive_int(self, key, value):
+        """Store *value* as a positive ``int``; ``None`` removes the key.
+
+        Raises:
+            ValueError: for anything that is not a positive integer or a
+                string of digits (``bool`` included: it is an ``int``).
+        """
+        if value is None:
+            self.pop(key, None)
+            return
+        if isinstance(value, bool):
+            raise ValueError(f"Media {key} must be a positive integer, not {value!r}")
+        if isinstance(value, str) and value.isdigit():
+            value = int(value)
+        if not isinstance(value, int) or value <= 0:
+            raise ValueError(f"Media {key} must be a positive integer, not {value!r}")
+        super().__setitem__(key, value)
+
+    def get_pixel_width(self):
+        """Width in pixels of the media's first video stream, or ``None``."""
+        return self._get_optional('pixel_width')
+
+    def set_pixel_width(self, pixel_width):
+        """Set the width in pixels; ``None`` removes it."""
+        self._set_positive_int('pixel_width', pixel_width)
+
+    pixel_width = property(get_pixel_width, set_pixel_width)
+
+    def get_pixel_height(self):
+        """Height in pixels of the media's first video stream, or ``None``."""
+        return self._get_optional('pixel_height')
+
+    def set_pixel_height(self, pixel_height):
+        """Set the height in pixels; ``None`` removes it."""
+        self._set_positive_int('pixel_height', pixel_height)
+
+    pixel_height = property(get_pixel_height, set_pixel_height)
+
+    def get_file_size(self):
+        """Size in bytes of the file the dimensions were measured on, or ``None``."""
+        return self._get_optional('file_size')
+
+    def set_file_size(self, file_size):
+        """Set the file size in bytes; ``None`` removes it."""
+        self._set_positive_int('file_size', file_size)
+
+    file_size = property(get_file_size, set_file_size)
+
+    def get_file_md5(self):
+        """The file's MD5 (32 lowercase hex digits), or ``None``. Every media
+        type; it comes from the upload, which already carries it (D18)."""
+        return self._get_optional('file_md5')
+
+    def set_file_md5(self, file_md5):
+        """Set the file's MD5 (any case, stored lowercase); ``None`` removes it.
+
+        Raises:
+            ValueError: for anything that is not 32 hex digits.
+        """
+        if file_md5 is None:
+            self.pop('file_md5', None)
+            return
+        if not isinstance(file_md5, str) or len(file_md5) != 32 or any(
+            c not in '0123456789abcdef' for c in file_md5.lower()
+        ):
+            raise ValueError(f"Media file_md5 must be 32 hex digits, not {file_md5!r}")
+        super().__setitem__('file_md5', file_md5.lower())
+
+    file_md5 = property(get_file_md5, set_file_md5)
+
 class MediaCue(Cue):
     """Base class for media-related cues (audio and video).
     

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/cues/VideoCue.py

@@ -1,27 +1,32 @@
 from .MediaCue import MediaCue
 from ..tools.CTimecode import CTimecode
+from ..helpers import ensure_items
 from ..log import Logger
 
+REQ_ITEMS = {
+    'opacity': 100  # Default to fully opaque — 0-100 percent scale (cms:PercentType)
+}
 
 
 class VideoCue(MediaCue):
     """A cue for handling video playback and control.
-    
+
     This class extends MediaCue to provide specific functionality for video playback,
     including frame rate handling and OSC communication for video routing.
     """
-    
+
     def __init__(self, init_dict = None):
         """Initialize a VideoCue.
-        
+
         Args:
             init_dict (dict, optional): Dictionary containing initialization values.
                 If provided, will be used to set initial properties.
         """
         if not init_dict:
-            super().__init__()
+            init_dict = REQ_ITEMS
         else:
-            super().__init__(init_dict)
+            init_dict = ensure_items(init_dict, REQ_ITEMS)
+        super().__init__(init_dict)
 
         self._player = None
         self._osc_route = None
@@ -31,6 +36,36 @@ class VideoCue(MediaCue):
         self._start_mtc = CTimecode(framerate=25)
         self._end_mtc = CTimecode(framerate=25)
 
+    def get_opacity(self):
+        """Get the cue's configured opacity level.
+
+        Returns:
+            int: The opacity level, 0-100 (applied uniformly across all
+                layers of this cue).
+        """
+        return super().__getitem__('opacity')
+
+    def set_opacity(self, opacity):
+        """Set the cue's configured opacity level.
+
+        Args:
+            opacity (int): The new opacity level, 0-100.
+        """
+        super().__setitem__('opacity', opacity)
+
+    opacity = property(get_opacity, set_opacity)
+
+    def items(self):
+        """Get all items in the cue as a dictionary.
+
+        Returns:
+            dict_items: A view of the cue's items, with required items sorted first.
+        """
+        x = dict(super().items())
+        for k in sorted(REQ_ITEMS.keys()):
+            x[k] = self[k]
+        return x.items()
+
     def player(self, player):
         """Set the video player instance.
         
@@ -41,21 +76,12 @@ class VideoCue(MediaCue):
 
     def osc_route(self, osc_route):
         """Set the OSC route for video control.
-        
+
         Args:
             osc_route (str): The OSC route to use for video control.
         """
         self._osc_route = osc_route
 
-    def items(self):
-        """Get all items in the cue as a dictionary.
-        
-        Returns:
-            dict_items: A view of the cue's items.
-        """
-        x = dict(super().items())
-        return x.items()
-
     def stop(self):
         """Stop the video playback.
         

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/log.py

@@ -1,12 +1,28 @@
 import sys
-from logging import getLogger, LoggerAdapter, StreamHandler, Formatter, DEBUG, INFO, ERROR, WARNING, CRITICAL
+from logging import getLogger, LoggerAdapter, NullHandler, StreamHandler, Formatter, DEBUG, INFO, ERROR, WARNING, CRITICAL
 from logging.handlers import SysLogHandler
 from functools import wraps
 from os import environ
+from os.path import basename
 import inspect
 
 cuemsFormatter = Formatter('[%(asctime)s][%(levelname)s] \tFormitGo (PID: %(process)d)-(%(threadName)-9s)-(%(name)s:%(funcName)s:%(caller)s)> %(message)s')
 
+# Third-party libraries sometimes call the module-level logging.info()/
+# warning() helpers at import time (pyossia does, from cuemsengine.osc).
+# Those helpers run logging.basicConfig() whenever the root logger has no
+# handlers, which attaches a StreamHandler(stderr) using logging.BASIC_FORMAT
+# to root. Since the loggers built below propagate, every CUEMS record then
+# gets re-emitted through that handler as a second, differently formatted
+# line — on top of the stdout and syslog copies. Under systemd all of them
+# land in the same journal, so each message was recorded three times.
+#
+# Seeding root with a NullHandler makes the implicit basicConfig() a no-op:
+# it returns early once root has any handler. Propagation is deliberately
+# left enabled — pytest's caplog fixture captures through a root handler and
+# depends on records reaching it.
+getLogger().addHandler(NullHandler())
+
 # Cache for module-specific loggers to avoid duplicate handlers
 _logger_cache = {}
 
@@ -41,22 +57,42 @@ class CuemsLoggerAdapter(LoggerAdapter):
         kwargs['extra'] = extra
         return msg, kwargs
 
+def _syslog_ident():
+    """
+    Tag to prefix onto /dev/log datagrams, e.g. 'controller-engine: '.
+
+    journald derives SYSLOG_IDENTIFIER by parsing a leading 'TAG:' or
+    'TAG[PID]:' off the datagram. Without one the entry carries no
+    identifier and journalctl falls back to _COMM, which the kernel
+    truncates to 15 characters — 'controller-engine' rendered as
+    'controller-engi', looking like a second, unrelated process.
+
+    The PID is deliberately left out: journald fills _PID from the socket
+    credentials, so it is always right, whereas a tag built once at handler
+    creation would go stale across a fork.
+    """
+    name = basename(sys.argv[0] or '') or 'cuems'
+    return f'{name}: '
+
 def main_logger(module_name = None, with_syslog = True, with_stdout = True):
     """
     Create a root logger with a custom formatter.
-    
+
     Args:
         module_name: Name of the module to create logger for. Defaults to __name__ if None.
         with_syslog: Whether to add syslog handler.
         with_stdout: Whether to add stdout handler.
+
+    Under systemd both handlers terminate in the same journal, so only the
+    syslog one is attached there — see the comment on the stdout branch.
     """
     if module_name is None:
         module_name = __name__
-    
+
     # Return cached logger if it exists
     if module_name in _logger_cache:
         return _logger_cache[module_name]
-    
+
     logger = getLogger(module_name)
     try:
         log_level = log_level_to_obj(environ['CUEMS_LOG_LEVEL'].upper())
@@ -64,16 +100,31 @@ def main_logger(module_name = None, with_syslog = True, with_stdout = True):
         log_level = DEBUG
     logger.setLevel(log_level)
 
-    if with_stdout:
+    # Under systemd, stdout and /dev/log both terminate in journald, so
+    # attaching both handlers records every message twice. Keep the syslog
+    # one: it is the only copy that carries the record's real priority.
+    # systemd stamps every stdout line PRIORITY=6 (info) regardless of the
+    # Python level, so a journalctl -p filter — which is what
+    # `cuems-logs -l/--level` and `-e/--errors` are built on — cannot tell a
+    # DEBUG line from an ERROR one on the stdout copy.
+    #
+    # JOURNAL_STREAM is set by systemd exactly when stdout/stderr are wired
+    # to the journal. When it is absent (interactive runs, pytest, a
+    # container logging elsewhere) stdout is attached as before, so running
+    # a component by hand still prints to the terminal.
+    journald_stdout = with_syslog and 'JOURNAL_STREAM' in environ
+
+    if with_stdout and not journald_stdout:
         sh = StreamHandler(sys.stdout)
         sh.setFormatter(cuemsFormatter)
         logger.addHandler(sh)
-    
+
     if with_syslog:
         syslog_handler = SysLogHandler(
             address = '/dev/log', facility = 'local0'
         )
         syslog_handler.setFormatter(cuemsFormatter)
+        syslog_handler.ident = _syslog_ident()
         logger.addHandler(syslog_handler)
 
     logger_adapter = CuemsLoggerAdapter(logger, {})

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/tools/HubServices.py

@@ -429,6 +429,8 @@ class NngBusHub(HubService):
         The loop runs until cancelled or an unhandled exception occurs.
         """
         while await asyncio.sleep(0, result=True):
+            if self._closing:
+                return
             try:
                 pynng_message = await self.connection.arecv_msg()
                 
@@ -463,6 +465,17 @@ class NngBusHub(HubService):
                     
             except pynng_exceptions.Timeout:
                 pass  # Timeout is expected during polling
+            except pynng_exceptions.Closed:
+                # The socket is gone — either an orderly teardown, or pynng's
+                # atexit hook already ran nng_fini() and freed NNG's global
+                # state. Retrying would call nng_recv_aio() on that freed
+                # state, which aborts the whole process with
+                # "panic: pthread_mutex_lock: Invalid argument". Stop for good.
+                self._closing = True
+                Logger.info(
+                    f"NNG {self.mode.value} receiver: socket closed, stopping loop"
+                )
+                return
             except Exception as e:
                 Logger.error(f"Error in receiver handler: {e}, type: {type(e)}")
 
@@ -528,6 +541,8 @@ class NngBusHub(HubService):
             Logger.info(f"Node connected, sender ready ({len(self.active_connections)} connections)")
         
         while await asyncio.sleep(0, result=True):
+            if self._closing:
+                return
             try:
                 message = await self.outgoing.get()
                 
@@ -544,6 +559,14 @@ class NngBusHub(HubService):
                 Logger.debug(f"[SEND #{self._messages_sent_count}] {self.mode.value} sending: type={msg_type}")
                 
                 await self.connection.asend(message.encode())
+            except pynng_exceptions.Closed:
+                # Same rule as the receiver: never touch NNG again once the
+                # socket is closed (see _receiver_handler).
+                self._closing = True
+                Logger.info(
+                    f"NNG {self.mode.value} sender: socket closed, stopping loop"
+                )
+                return
             except Exception as e:
                 Logger.error(f"Error in send handler: {e}, type: {type(e)}")
 

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/xml/Parsers.py

@@ -1,3 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Stagelab Coop SCCL
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
 from ..cues import *
 from ..cues.FadeProfile import FadeFunctionParameter, FadeProfile
 from ..cues.MediaCue import Media, Region
@@ -33,6 +36,9 @@ STRING_TYPED_KEYS = frozenset({
     'name', 'description', 'file_name',
     # defensive -- see above
     'output_name', 'parameter_name', 'icon', 'color', 'unix_name',
+    # an MD5 is hex: about one in a million is all digits (-> int) or digits
+    # with one 'e' (-> float), and would no longer validate (869fat84r D18)
+    'file_md5',
 })
 
 class GenericDict(dict):

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/xml/XmlBuilder.py

@@ -1,3 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Stagelab Coop SCCL
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
 from enum import Enum
 from xml.etree.ElementTree import Element, ElementTree, SubElement, register_namespace
 
@@ -170,10 +173,34 @@ class GenericComplexSubObjectXmlBuilder(CuemsScriptXmlBuilder):
 class CTimecodeXmlBuilder(GenericSimpleSubObjectXmlBuilder):
     pass
 
+#: ``MediaType``'s element order in script.xsd. The writer follows it, not the
+#: dict's order: the editor appends the stored dimensions after whatever the
+#: frontend sent, and the parsers assign keys in arrival order (869fat84r).
+MEDIA_ELEMENT_ORDER = (
+    'file_name', 'id', 'duration', 'regions',
+    'pixel_width', 'pixel_height', 'file_size', 'file_md5',
+)
+
+#: Optional MediaType elements: a ``None`` value writes no element at all
+#: (an empty ``<pixel_width/>`` would fail ``xs:positiveInteger``).
+MEDIA_OPTIONAL_ELEMENTS = frozenset({'pixel_width', 'pixel_height', 'file_size', 'file_md5'})
+
+
+def _media_items_in_schema_order(media):
+    """``media``'s items, known keys in schema order, then any others in
+    arrival order (so the validator, not this writer, rejects them)."""
+    known = [(k, media[k]) for k in MEDIA_ELEMENT_ORDER if k in media]
+    other = [(k, v) for k, v in media.items() if k not in MEDIA_ELEMENT_ORDER]
+    return [
+        (k, v) for k, v in known + other
+        if not (v is None and k in MEDIA_OPTIONAL_ELEMENTS)
+    ]
+
+
 class MediaXmlBuilder(GenericComplexSubObjectXmlBuilder):
     def build(self):
         if isinstance(self._object, dict):
-            for key, value in self._object.items():
+            for key, value in _media_items_in_schema_order(self._object):
                 if isinstance(value, VALUE_TYPES):
                     cue_subelement = SubElement(self.xml_tree, key)
                     cue_subelement.text = str(value)
@@ -334,7 +361,7 @@ class MediaCueXmlBuilder(GenericCueXmlBuilder):
                 builder_class(value, xml_tree=cue_subelement).build()
             cls_name = type(self._object).__name__
             if key == 'master_vol' or (
-                key == 'outputs' and cls_name == 'VideoCue'
+                key == 'opacity' and cls_name == 'VideoCue'
             ):
                 fps = self._object.get('fade_profiles')
                 if fps:

{cuemsutils-0.1.0rc11 → cuemsutils-0.1.0rc15}/cuemsutils/xml/schemas/script.xsd

@@ -1,4 +1,9 @@
 <?xml version="1.1" encoding="utf-8"?>
+<!--
+SPDX-FileCopyrightText: 2026 Stagelab Coop SCCL
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileContributor: Ion Reguera <ion@stagelab.coop>
+-->
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" vc:minVersion="1.1" targetNamespace="https://stagelab.coop/cuems/" xmlns:cms="https://stagelab.coop/cuems/">
   <!-- The main capsule to make it a whole, named CueMs -->
   <!-- Our main object the script-->
@@ -181,9 +186,31 @@
       <xs:element name="id" type="cms:TargetType" />
       <xs:element name="duration" type="cms:TimecodeType" />
       <xs:element name="regions" type="cms:RegionsType" />
+      <!-- Stored size of the media file (869fat84r), measured by the editor
+           at upload so the engine does not probe the file when it arms a cue.
+           pixel_width / pixel_height: the ORIGINAL size of the file's first
+           video stream, as ffprobe reports it; not the layer's size on screen
+           (that would get its own names) and unrelated to CanvasRegionType's
+           unit-float width / height. file_size: the file's size in bytes when
+           they were measured; the engine compares it with its own copy to
+           notice a file replaced under the same name. Optional: absent means
+           unknown, and the engine then probes as before. The pixel size is
+           for VideoCues only; file_size and file_md5 for every media type.
+           file_md5: the file's MD5 (lowercase hex), from the upload, which
+           already carries it; identifies the file for integrity checks. -->
+      <xs:element name="pixel_width" type="xs:positiveInteger" minOccurs="0" />
+      <xs:element name="pixel_height" type="xs:positiveInteger" minOccurs="0" />
+      <xs:element name="file_size" type="xs:positiveInteger" minOccurs="0" />
+      <xs:element name="file_md5" type="cms:Md5Type" minOccurs="0" />
     </xs:sequence>
   </xs:complexType>
 
+  <xs:simpleType name="Md5Type">
+    <xs:restriction base="xs:string">
+      <xs:pattern value="[0-9a-f]{32}" />
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="OutputsType">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="AudioCueOutput" type="cms:AudioCueOutputsType" />
@@ -251,12 +278,18 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <!-- linear/sigmoid/ease_in/ease_out are the curves gradient-motiond's
+       CurveFactory implements (the editor UI submits only these);
+       exponential/logarithmic are legacy names kept so old projects still
+       load — the frontend heals them to ease_in/ease_out on next save. -->
   <xs:simpleType name="FadeCurveType">
     <xs:restriction base="xs:string">
       <xs:enumeration value="linear" />
       <xs:enumeration value="exponential" />
       <xs:enumeration value="logarithmic" />
       <xs:enumeration value="sigmoid" />
+      <xs:enumeration value="ease_in" />
+      <xs:enumeration value="ease_out" />
     </xs:restriction>
   </xs:simpleType>
 
@@ -312,6 +345,10 @@
     <xs:complexContent>
       <xs:extension base="cms:MediaCueType">
         <xs:sequence>
+          <!-- Optional (unlike AudioCue's master_vol) to stay backward-compatible
+               with existing project files authored before this field existed;
+               absent -> Python-side REQ_ITEMS default of 100 (fully opaque). -->
+          <xs:element name="opacity" type="cms:PercentType" minOccurs="0" />
           <xs:element name="fade_profiles" type="cms:FadeProfilesWrapperType" minOccurs="0" />
         </xs:sequence>
       </xs:extension>