Add emit initial delay option for widget audio emit

server/app/item_catalog.py

@@ -113,6 +113,11 @@ GLOBAL_ITEM_PROPERTY_METADATA: dict[str, dict[str, object]] = {
         "tooltip": "Global emitted sound tempo percent. 50 is normal.",
         "range": {"min": 0, "max": 100, "step": 0.1},
     },
+    "emitInitialDelay": {
+        "valueType": "number",
+        "tooltip": "Delay in seconds before emitted audio starts after this sound is enabled.",
+        "range": {"min": 0, "max": 300, "step": 0.1},
+    },
     "emitLoopDelay": {
         "valueType": "number",
         "tooltip": "Delay in seconds between each emitted playback.",
@@ -159,5 +164,6 @@ def get_item_global_properties(item_type: ItemType) -> dict[str, str | int | boo
         "directional": bool(definition.directional),
         "emitSoundSpeed": 50,
         "emitSoundTempo": 50,
+        "emitInitialDelay": 0,
         "emitLoopDelay": 0,
     }

server/app/items/types/widget/definition.py

@@ -13,6 +13,7 @@ EDITABLE_PROPERTIES: tuple[str, ...] = (
     "emitVolume",
     "emitSoundSpeed",
     "emitSoundTempo",
+    "emitInitialDelay",
     "emitLoopDelay",
     "emitEffect",
     "emitEffectValue",
@@ -34,6 +35,7 @@ DEFAULT_PARAMS: dict = {
     "emitVolume": 100,
     "emitSoundSpeed": 50,
     "emitSoundTempo": 50,
+    "emitInitialDelay": 0,
     "emitLoopDelay": 0,
     "emitEffect": "off",
     "emitEffectValue": 50,
@@ -48,6 +50,7 @@ PARAM_KEYS: tuple[str, ...] = (
     "emitVolume",
     "emitSoundSpeed",
     "emitSoundTempo",
+    "emitInitialDelay",
     "emitLoopDelay",
     "emitEffect",
     "emitEffectValue",
@@ -86,6 +89,11 @@ PROPERTY_METADATA: dict[str, dict[str, object]] = {
         "tooltip": "Playback tempo percent for emitted sound. 50 is normal, 0 is half, 100 is double. Using speed and tempo together may sound weird.",
         "range": {"min": 0, "max": 100, "step": 0.1},
     },
+    "emitInitialDelay": {
+        "valueType": "number",
+        "tooltip": "Delay in seconds before emitted audio starts after this sound is enabled.",
+        "range": {"min": 0, "max": 300, "step": 0.1},
+    },
     "emitLoopDelay": {
         "valueType": "number",
         "tooltip": "Delay in seconds between each playing of this audio.",

server/app/items/types/widget/validator.py

@@ -56,6 +56,14 @@ def validate_update(item: WorldItem, next_params: dict) -> dict:
         raise ValueError("emitSoundTempo must be between 0 and 100.")
     next_params["emitSoundTempo"] = round(emit_tempo, 1)
 
+    try:
+        emit_initial_delay = float(next_params.get("emitInitialDelay", item.params.get("emitInitialDelay", 0)))
+    except (TypeError, ValueError) as exc:
+        raise ValueError("emitInitialDelay must be a number between 0 and 300.") from exc
+    if not (0 <= emit_initial_delay <= 300):
+        raise ValueError("emitInitialDelay must be between 0 and 300.")
+    next_params["emitInitialDelay"] = round(emit_initial_delay, 1)
+
     try:
         emit_loop_delay = float(next_params.get("emitLoopDelay", item.params.get("emitLoopDelay", 0)))
     except (TypeError, ValueError) as exc: