frontengine 1.0.26__tar.gz → 1.0.27__tar.gz

{frontengine-1.0.26 → frontengine-1.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.26
+Version: 1.0.27
 Summary: FrontEngine is use-define frontview or only use like screen saver
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/Intergration-Automation-Testing/FrontEngine
@@ -53,6 +53,33 @@ It provides an intuitive interface and supports multiple media formats for inter
 
 ---
 
+## Desktop pet
+
+Spawn an animated sprite that lives on your desktop, from the **Pet** tab.
+
+- **Sprites** — pick a single GIF/WebP/PNG, or a *pet pack* folder whose file
+  names map to states: `walk`, `idle`, `sleep`, `climb`, `fall`, `drag`
+  (missing states fall back to `walk`).
+- **Behaviour** — walk on the floor with gravity (throw it and it bounces),
+  wander freely, or chase the cursor. Floor pets can climb screen edges and
+  stand on the top edge of other windows.
+- **Life** — mood, fullness and an affection level that persist between runs;
+  the pet grows as it levels up, chats in speech bubbles, naps while you are
+  away, and warns you about a low battery.
+- **Interaction** — drag it around, right-click to clone/feed/set a reminder,
+  and **drop a file onto it**: an image or pet pack becomes its new look,
+  anything else is eaten as a snack.
+- **React to audio** — the pet pulses to your speakers' output level. It reads
+  only the Windows output *meter* (WASAPI `IAudioMeterInformation`); no audio
+  is captured or recorded. Peaks are smoothed with an RMS window and a
+  fast-attack/slow-decay envelope so the pulse breathes instead of flickering.
+  On multi-monitor setups each pet follows the audio endpoint that matches its
+  own screen, falling back to the default output device.
+
+Audio features are Windows-only and degrade to "no pulse" elsewhere.
+
+---
+
 ## Install
 
 - **System Requirements**

{frontengine-1.0.26 → frontengine-1.0.27}/README.md

@@ -29,6 +29,33 @@ It provides an intuitive interface and supports multiple media formats for inter
 
 ---
 
+## Desktop pet
+
+Spawn an animated sprite that lives on your desktop, from the **Pet** tab.
+
+- **Sprites** — pick a single GIF/WebP/PNG, or a *pet pack* folder whose file
+  names map to states: `walk`, `idle`, `sleep`, `climb`, `fall`, `drag`
+  (missing states fall back to `walk`).
+- **Behaviour** — walk on the floor with gravity (throw it and it bounces),
+  wander freely, or chase the cursor. Floor pets can climb screen edges and
+  stand on the top edge of other windows.
+- **Life** — mood, fullness and an affection level that persist between runs;
+  the pet grows as it levels up, chats in speech bubbles, naps while you are
+  away, and warns you about a low battery.
+- **Interaction** — drag it around, right-click to clone/feed/set a reminder,
+  and **drop a file onto it**: an image or pet pack becomes its new look,
+  anything else is eaten as a snack.
+- **React to audio** — the pet pulses to your speakers' output level. It reads
+  only the Windows output *meter* (WASAPI `IAudioMeterInformation`); no audio
+  is captured or recorded. Peaks are smoothed with an RMS window and a
+  fast-attack/slow-decay envelope so the pulse breathes instead of flickering.
+  On multi-monitor setups each pet follows the audio endpoint that matches its
+  own screen, falling back to the default output device.
+
+Audio features are Windows-only and degrade to "no pulse" elsewhere.
+
+---
+
 ## Install
 
 - **System Requirements**

{frontengine-1.0.26 → frontengine-1.0.27}/frontengine/show/pet/desktop_pet.py

@@ -12,6 +12,7 @@ from PySide6.QtWidgets import QMenu, QMessageBox, QWidget
 from frontengine.show.base_widget import BaseWidget
 from frontengine.show.window_helpers import apply_overlay_window_flags
 from frontengine.user_setting.user_setting_file import user_setting_dict
+from frontengine.utils.audio_meter.audio_envelope import AudioEnvelope
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
@@ -82,6 +83,28 @@ def scan_pet_pack(folder: str) -> dict:
     return result
 
 
+# 拖進寵物的檔案分類 / What a file dropped onto the pet means
+DROP_SPRITE = "sprite"  # 圖片或動作包 -> 換一套外觀
+DROP_FOOD = "food"      # 其他檔案 -> 當成食物餵給寵物
+
+
+def classify_drop(path) -> Optional[str]:
+    """
+    判斷拖到寵物身上的檔案要換裝還是當食物；路徑無效或空資料夾回傳 None。
+    Classify a file dropped onto the pet: a sprite/pack to wear, food to eat,
+    or None when the path is unusable.
+    """
+    try:
+        target = Path(path)
+        if not target.exists():
+            return None
+    except (OSError, TypeError, ValueError):
+        return None
+    if target.is_dir():
+        return DROP_SPRITE if scan_pet_pack(str(target)) else None
+    return DROP_SPRITE if target.suffix.lower() in _PACK_EXTS else DROP_FOOD
+
+
 def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_state: str) -> str:
     """依目前情形推導應顯示的視覺狀態 / Derive which sprite state to show."""
     if dragging:
@@ -876,6 +899,7 @@ class DesktopPetWidget(BaseWidget):
             message_box.show()
 
         self.resize(self.pet_size, self.pet_size)
+        self.setAcceptDrops(True)  # drop an image to dress it up, anything else to feed it
         self.motion = PetMotion(
             0, 0, self.pet_size, self.pet_size, (0, 0, 1920, 1080), speed, behaviour, climb=climb
         )
@@ -901,6 +925,9 @@ class DesktopPetWidget(BaseWidget):
         self._audio_react = bool(audio_react)
         self._audio_level_provider = None  # callable -> level 0..1 or None
         self._audio_scale = 1.0
+        # 峰值抖動大，先過 RMS + 快起慢降包絡再驅動脈動
+        # Raw peaks jitter, so smooth them through an RMS + attack/decay envelope.
+        self._audio_envelope = AudioEnvelope()
         # 多寵物互動 / Multi-pet interaction
         self._peers_provider = None
         self._peer_greeted = False
@@ -992,19 +1019,50 @@ class DesktopPetWidget(BaseWidget):
             self._peer_greeted = False
 
     def _load_sprite(self, path: str):
+        """載入一張精靈；檔案損毀或格式不支援時回傳 None。"""
         if Path(path).suffix.lower() in (".gif", ".webp"):
             movie = QMovie(str(path))
+            if not movie.isValid():
+                return None
             movie.frameChanged.connect(self.update)
             return ("movie", movie)
-        return ("pixmap", QPixmap(str(path)))
+        pixmap = QPixmap(str(path))
+        return None if pixmap.isNull() else ("pixmap", pixmap)
 
     def _load_sprites(self, image_path: Path) -> None:
-        """單一檔 -> 所有狀態共用；資料夾 -> 依檔名對應各狀態。"""
+        """單一檔 -> 所有狀態共用；資料夾 -> 依檔名對應各狀態；載不起來的略過。"""
         if image_path.is_dir():
             for state, path in scan_pet_pack(str(image_path)).items():
-                self._sprites[state] = self._load_sprite(path)
+                sprite = self._load_sprite(path)
+                if sprite is not None:
+                    self._sprites[state] = sprite
         elif image_path.is_file():
-            self._sprites["default"] = self._load_sprite(str(image_path))
+            sprite = self._load_sprite(str(image_path))
+            if sprite is not None:
+                self._sprites["default"] = sprite
+
+    def change_sprite(self, path) -> None:
+        """換一套外觀（拖圖片或動作包到寵物身上時觸發）；載不到就維持原樣。"""
+        image_path = Path(path)
+        previous = self._sprites
+        self._sprites = {}
+        self._load_sprites(image_path)
+        if not self._sprites:
+            front_engine_logger.warning(f"[DesktopPetWidget] change_sprite ignored: {image_path}")
+            self._sprites = previous
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] change_sprite | path={image_path}")
+        for kind, obj in previous.values():
+            if kind == "movie":
+                obj.stop()
+        self.image_path = image_path
+        self._active = None
+        self._active_state = None
+        self._set_active_sprite(self._visual_state())
+        self._gain_affection(2)
+        pool = self._messages.get("costume") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
 
     def _sprite_for(self, state: str):
         if "default" in self._sprites:
@@ -1042,16 +1100,23 @@ class DesktopPetWidget(BaseWidget):
     def set_audio_level_provider(self, provider) -> None:
         """設定回傳目前音量 (0~1 或 None) 的函式 / Provider of the current audio level."""
         self._audio_level_provider = provider
+        self._audio_envelope.reset()
 
     def _update_audio_scale(self) -> None:
+        """取一次音量取樣，經包絡平滑後換算成脈動比例（無音源則不脈動）。"""
         if not self._audio_react or self._audio_level_provider is None:
             self._audio_scale = 1.0
+            self._audio_envelope.reset()
             return
         try:
             level = self._audio_level_provider()
         except Exception:  # pragma: no cover - defensive
             level = None
-        self._audio_scale = 1.0 if level is None else audio_pulse_scale(level)
+        if level is None:
+            self._audio_scale = 1.0
+            self._audio_envelope.reset()
+            return
+        self._audio_scale = audio_pulse_scale(self._audio_envelope.push(level))
 
     def draw_content(self, painter: QPainter) -> None:
         pixmap = self._current_pixmap()
@@ -1101,6 +1166,7 @@ class DesktopPetWidget(BaseWidget):
             "fed": lines("pet_chatter_fed", "Yum!|Thank you!|Delicious!"),
             "away": lines("pet_chatter_away", "Still there?|I'll nap till you're back~|Zzz..."),
             "levelup": lines("pet_chatter_levelup", "Level up!|I'm growing!|We're getting closer!"),
+            "costume": lines("pet_chatter_costume", "New look!|How do I look?|Nice fit!"),
             "any": lines("pet_chatter_any", "Hi there!|(^_^)|Keep going!"),
         }
 
@@ -1389,6 +1455,38 @@ class DesktopPetWidget(BaseWidget):
                 self.say()  # a click (no drag) makes the pet talk
         super().mouseReleaseEvent(event)
 
+    # --- drop a file onto the pet: wear it (image / pack) or eat it ---
+    @staticmethod
+    def dropped_path(mime_data) -> Optional[str]:
+        """從拖曳資料取出第一個可用的本機路徑；沒有可用者回傳 None。"""
+        if mime_data is None or not mime_data.hasUrls():
+            return None
+        for url in mime_data.urls():
+            local_path = url.toLocalFile()
+            if local_path and classify_drop(local_path) is not None:
+                return local_path
+        return None
+
+    def dragEnterEvent(self, event) -> None:
+        if self.dropped_path(event.mimeData()) is not None:
+            event.acceptProposedAction()
+
+    def dragMoveEvent(self, event) -> None:
+        if self.dropped_path(event.mimeData()) is not None:
+            event.acceptProposedAction()
+
+    def dropEvent(self, event) -> None:
+        path = self.dropped_path(event.mimeData())
+        if path is None:
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}")
+        self.motion.wake()
+        if classify_drop(path) == DROP_SPRITE:
+            self.change_sprite(path)
+        else:
+            self.feed()
+        event.acceptProposedAction()
+
     def contextMenuEvent(self, event) -> None:
         self.menu.popup(event.globalPos())
 

{frontengine-1.0.26 → frontengine-1.0.27}/frontengine/ui/page/pet/pet_setting_ui.py

@@ -17,7 +17,7 @@ from frontengine.ui.page.utils import (
     resolve_preferred_monitor,
 )
 from frontengine.user_setting.user_setting_file import add_recent_file
-from frontengine.utils.audio_meter.system_audio_meter import system_audio_level
+from frontengine.utils.audio_meter.screen_audio import audio_level_provider_for_screen
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
@@ -93,6 +93,12 @@ class PetSettingUI(QWidget):
         self.volume_combobox.setCurrentText("100%")
         self.audio_react_checkbox = QCheckBox(
             language_wrapper.language_word_dict.get("pet_audio_label", "React to audio"))
+        self.drop_hint_label = QLabel(
+            language_wrapper.language_word_dict.get(
+                "pet_drop_hint",
+                "Tip: drop an image or pet pack onto the pet to change its look, "
+                "or any other file to feed it."))
+        self.drop_hint_label.setWordWrap(True)
 
         # Start
         self.start_button = QPushButton(language_wrapper.language_word_dict.get("pet_start", "Spawn pet"))
@@ -128,6 +134,7 @@ class PetSettingUI(QWidget):
         self.grid_layout.addWidget(self.volume_label, 6, 2)
         self.grid_layout.addWidget(self.volume_combobox, 7, 2)
         self.grid_layout.addWidget(self.audio_react_checkbox, 7, 0)
+        self.grid_layout.addWidget(self.drop_hint_label, 8, 0, 1, 3)
 
     def _spawn_pet(self) -> None:
         """建立、顯示並開始移動一隻寵物（供 Start 與右鍵複製共用）。"""
@@ -147,12 +154,15 @@ class PetSettingUI(QWidget):
         )
         pet.clone_requested.connect(self._spawn_pet)
         pet.set_peers_provider(lambda me=pet: self._peer_centers(me))
+        geometry = self._target_geometry()
         if self.audio_react_checkbox.isChecked():
-            pet.set_audio_level_provider(system_audio_level)  # real system output peak meter
+            # 跟隨寵物所在螢幕的音源（比對不到就用系統預設輸出裝置）
+            # Follow the audio of the screen the pet lives on; default endpoint otherwise.
+            pet.set_audio_level_provider(
+                audio_level_provider_for_screen(geometry[1] if geometry is not None else None))
         pet.set_pet_window_flag()
         self.pet_list.append(pet)
         pet.show()
-        geometry = self._target_geometry()
         if geometry is not None:
             pet.setScreen(geometry[1])
             bounds = geometry[0]

frontengine-1.0.27/frontengine/utils/audio_meter/audio_envelope.py

@@ -0,0 +1,56 @@
+"""
+把逐次取樣的音量峰值平滑成自然的脈動包絡：先在短窗內取 RMS 壓掉抖動，
+再以「快起慢降」的包絡追蹤器塑形，避免忽大忽小的閃爍。純邏輯、不依賴 Qt。
+
+Smooth per-tick peak samples into a natural pulse envelope: a short RMS window
+removes jitter, then an asymmetric follower (fast attack, slow decay) shapes it.
+Pure logic, no Qt dependency.
+"""
+from __future__ import annotations
+
+from collections import deque
+
+
+def clamp_level(value) -> float:
+    """把任意輸入夾到 0~1；無法轉成數值時回傳 0.0。"""
+    try:
+        return max(0.0, min(1.0, float(value)))
+    except (TypeError, ValueError):
+        return 0.0
+
+
+class AudioEnvelope:
+    """
+    音量包絡追蹤器：push() 餵進一個 0~1 的峰值取樣，回傳平滑後的 0~1 音量。
+    window 為 RMS 取樣窗長度，attack/decay 為上升/下降的追隨係數 (0~1，越大越快)。
+
+    An envelope follower: push() takes one 0..1 peak sample and returns the
+    smoothed 0..1 level. `window` is the RMS window length; `attack`/`decay`
+    are the rise/fall follow coefficients (0..1, larger is faster).
+    """
+
+    def __init__(self, window: int = 4, attack: float = 0.6, decay: float = 0.12) -> None:
+        self._window = max(1, int(window))
+        self._samples: deque = deque(maxlen=self._window)
+        self.attack = clamp_level(attack)
+        self.decay = clamp_level(decay)
+        self.value = 0.0
+
+    def reset(self) -> None:
+        """清空取樣與輸出（音源消失或關閉律動時呼叫）。"""
+        self._samples.clear()
+        self.value = 0.0
+
+    def rms(self) -> float:
+        """目前取樣窗的均方根；窗內無取樣時回傳 0.0。"""
+        if not self._samples:
+            return 0.0
+        return (sum(sample * sample for sample in self._samples) / len(self._samples)) ** 0.5
+
+    def push(self, level) -> float:
+        """餵入一個峰值取樣並回傳平滑後的音量 / Feed one peak sample, return the smoothed level."""
+        self._samples.append(clamp_level(level))
+        target = self.rms()
+        coefficient = self.attack if target > self.value else self.decay
+        self.value = clamp_level(self.value + coefficient * (target - self.value))
+        return self.value

frontengine-1.0.27/frontengine/utils/audio_meter/screen_audio.py

@@ -0,0 +1,130 @@
+"""
+把「螢幕」對應到「輸出音源端點」：多螢幕時，各螢幕常各自帶喇叭（HDMI/DP 音訊），
+本模組以端點顯示名稱與螢幕型號/製造商的共同字詞比對，讓每隻寵物跟著自己所在
+螢幕的聲音律動；比不到對應端點時退回預設輸出裝置。
+
+Map a screen to an audio output endpoint. On multi-monitor setups each screen
+often carries its own speakers (HDMI/DP audio); this matches endpoint friendly
+names against the screen's model/manufacturer so a pet pulses to the sound of
+the screen it lives on, falling back to the default endpoint when unmatched.
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from frontengine.utils.audio_meter.system_audio_meter import (
+    SystemAudioMeter, list_output_devices, system_audio_level,
+)
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+# 比對時要忽略的通用字詞（裝置與螢幕名稱都常出現，沒有辨識力）
+# Generic words that carry no identifying power when matching names.
+_GENERIC_TOKENS = frozenset({
+    "audio", "sound", "speaker", "speakers", "headphone", "headphones", "headset",
+    "digital", "output", "high", "definition", "device", "generic", "pnp", "plug",
+    "play", "monitor", "display", "screen", "hdmi", "displayport", "the", "and",
+    "nvidia", "intel", "amd", "realtek", "usb", "default", "communications",
+})
+
+
+def name_tokens(text) -> set:
+    """把名稱切成可比對的小寫字詞，去掉通用字詞與過短片段。"""
+    if not text:
+        return set()
+    tokens = set()
+    word = []
+    for character in str(text).lower():
+        if character.isalnum():
+            word.append(character)
+            continue
+        if word:
+            tokens.add("".join(word))
+            word = []
+    if word:
+        tokens.add("".join(word))
+    return {token for token in tokens if len(token) >= 2 and token not in _GENERIC_TOKENS}
+
+
+def match_device_for_screen(hints: Iterable[str], devices: Iterable[Tuple[str, str]]) -> Optional[str]:
+    """
+    以共同字詞數挑出最像該螢幕的輸出端點，回傳 device_id；沒有共同字詞回傳 None。
+    Pick the endpoint sharing the most tokens with the screen hints, or None.
+    """
+    hint_tokens = set()
+    for hint in hints or ():
+        hint_tokens |= name_tokens(hint)
+    if not hint_tokens:
+        return None
+    best_id = None
+    best_score = 0
+    for device_id, name in devices or ():
+        score = len(hint_tokens & name_tokens(name))
+        if score > best_score:
+            best_score = score
+            best_id = device_id
+    return best_id
+
+
+def screen_hints(screen) -> List[str]:
+    """從 QScreen 取出可比對的字串（型號、製造商、名稱），取不到就略過。"""
+    hints: List[str] = []
+    for attribute in ("model", "manufacturer", "name"):
+        getter = getattr(screen, attribute, None)
+        if not callable(getter):
+            continue
+        try:
+            value = getter()
+        except Exception as error:  # pragma: no cover - defensive against Qt/duck-typed screens
+            # 某個欄位問不到不影響其他欄位的比對，記錄後繼續。
+            # One attribute refusing to answer must not stop the remaining hints.
+            front_engine_logger.debug(f"[screen_hints] {attribute} failed: {error!r}")
+            continue
+        if value:
+            hints.append(str(value))
+    return hints
+
+
+class ScreenAudioMeters:
+    """依裝置 ID 快取電表，並提供「綁定某螢幕音源」的取樣函式。"""
+
+    def __init__(self) -> None:
+        self._meters: Dict[str, SystemAudioMeter] = {}
+
+    def device_for_screen(self, screen) -> Optional[str]:
+        """回傳該螢幕對應的輸出端點 ID；沒有對應者回傳 None。"""
+        if screen is None:
+            return None
+        return match_device_for_screen(screen_hints(screen), list_output_devices())
+
+    def level_for_device(self, device_id: str) -> Optional[float]:
+        """讀取指定端點的目前峰值（電表物件會重複使用）。"""
+        meter = self._meters.get(device_id)
+        if meter is None:
+            meter = SystemAudioMeter(device_id)
+            self._meters[device_id] = meter
+        return meter.level()
+
+    def provider_for_screen(self, screen):
+        """
+        回傳取樣函式：優先跟隨該螢幕的音源，比對不到則沿用系統預設輸出裝置。
+        Return a level provider bound to the screen's endpoint, or the default one.
+        """
+        device_id = self.device_for_screen(screen)
+        if device_id is None:
+            return system_audio_level
+        front_engine_logger.info(f"[ScreenAudioMeters] screen audio endpoint | id={device_id}")
+        return lambda: self.level_for_device(device_id)
+
+    def close(self) -> None:
+        """釋放所有已建立的電表 / Release every meter created so far."""
+        for meter in self._meters.values():
+            meter.close()
+        self._meters.clear()
+
+
+_screen_meters = ScreenAudioMeters()
+
+
+def audio_level_provider_for_screen(screen):
+    """便利函式：取得跟隨指定螢幕音源的取樣函式（共用電表快取）。"""
+    return _screen_meters.provider_for_screen(screen)