piwave 2.0.9__py3-none-any.whl → 2.1.1__py3-none-any.whl

piwave/__init__.py

@@ -1,4 +1,6 @@
-# piwave/__init__.py
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/__init__.py : whats this again ?
 
 from .piwave import PiWave
 

piwave/__main__.py

@@ -0,0 +1,105 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/__main__.py : handles cli inputs
+
+import sys
+import argparse
+from .backends import search_backends, list_backends, backends, discover_backends
+from .logger import Log
+from .piwave import PiWave, PiWaveError
+
+def main():
+    if len(sys.argv) < 2:
+        Log.header("PiWave CLI")
+        Log.info("Usage: python3 -m piwave <command> [args]\n")
+        Log.info("Available commands:")
+        Log.info("  search       - Search for available backends")
+        Log.info("  list         - List cached backends")
+        Log.info("  add <name> <path> - Manually add backend executable path")
+        Log.info("  info         - Show package info")
+        Log.info("  broadcast <file>  - Broadcast a file over FM")
+        sys.exit(0)
+
+    cmd = sys.argv[1].lower()
+
+    if cmd == "search":
+        search_backends()
+
+    elif cmd == "list":
+        discover_backends()
+        list_backends()
+
+    elif cmd == "add":
+        if len(sys.argv) < 4:
+            Log.error("Usage: python3 -m piwave add <backend_name> <path>")
+            sys.exit(1)
+
+        backend_name = sys.argv[2]
+        backend_path = sys.argv[3]
+
+        discover_backends()
+        if backend_name not in backends:
+            Log.error(f"Unknown backend '{backend_name}'. Run `python3 -m piwave search` first.")
+            sys.exit(1)
+
+        backend_class = backends[backend_name]
+        try:
+            backend = backend_class()
+            backend.cache_file.write_text(backend_path)
+            Log.success(f"Backend '{backend_name}' path set to {backend_path}")
+        except Exception as e:
+            Log.error(f"Failed to add backend '{backend_name}': {e}")
+
+    elif cmd == "info":
+        Log.header("PiWave Module Info")
+        Log.info("Python-based FM transmitter manager for Raspberry Pi")
+        Log.info("Commands: search, list, add, info, broadcast")
+
+    elif cmd == "broadcast":
+        parser = argparse.ArgumentParser(
+            prog="python3 -m piwave broadcast",
+            description="Broadcast a file using PiWave"
+        )
+        parser.add_argument("file", help="Path to the audio file to broadcast")
+        parser.add_argument("--frequency", type=float, default=90.0, help="FM frequency (MHz)")
+        parser.add_argument("--ps", type=str, default="PiWave", help="Program Service name (max 8 chars)")
+        parser.add_argument("--rt", type=str, default="PiWave: The best python module for managing your pi radio", help="Radio Text (max 64 chars)")
+        parser.add_argument("--pi", type=str, default="FFFF", help="Program Identification code (4 hex digits)")
+        parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+        parser.add_argument("--silent", action="store_true", help="Suppress logs")
+        parser.add_argument("--loop", action="store_true", help="Loop playback")
+        parser.add_argument("--backend", type=str, default="auto", help="Choose a specific backend")
+
+        args = parser.parse_args(sys.argv[2:])
+
+        try:
+            pw = PiWave(
+                frequency=args.frequency,
+                ps=args.ps,
+                rt=args.rt,
+                pi=args.pi,
+                debug=args.debug,
+                silent=args.silent,
+                loop=args.loop,
+                backend=args.backend
+            )
+            pw.play(args.file)
+
+            Log.info("Press Ctrl+C to stop broadcasting...")
+            try:
+                while True:
+                    pass
+            except KeyboardInterrupt:
+                pw.stop()
+                Log.info("Broadcast stopped")
+        except PiWaveError as e:
+            Log.error(f"PiWaveError: {e}")
+            sys.exit(1)
+
+    else:
+        Log.error(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

piwave/backends/__init__.py

@@ -0,0 +1,126 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/backends/__init__.py : some utility funcs for backends
+
+from .pi_fm_rds import PiFmRdsBackend
+from .fm_transmitter import FmTransmitterBackend
+from ..logger import Log
+
+# auto discover backends
+backends = {}
+backend_classes = {
+    "pi_fm_rds": PiFmRdsBackend,
+    "fm_transmitter": FmTransmitterBackend
+}
+
+
+def get_best_backend(mode: str, frequency: float):
+    if mode == "file_broadcast":
+        if 88.0 <= frequency <= 108.0:
+            if "pi_fm_rds" in backends:
+                return "pi_fm_rds"
+            elif "fm_transmitter" in backends:
+                return "fm_transmitter"
+        else:
+            if "fm_transmitter" in backends:
+                return "fm_transmitter"
+            elif "pi_fm_rds" in backends:
+                return "pi_fm_rds"
+    
+    elif mode == "live_broadcast":
+        if "fm_transmitter" in backends:
+            backend = backends["fm_transmitter"]()
+            min_freq, max_freq = backend.frequency_range
+            if min_freq <= frequency <= max_freq:
+                return "fm_transmitter"
+        
+        return None
+    
+    return None
+
+def discover_backends():
+    """
+    Populate `backends` dictionary with available backends.
+    Reads cache files first, probes hardware only if no cache exists.
+    Stores executable path in cache if available, "None" otherwise.
+    """
+    backends.clear()
+
+    for name, backend_class in backend_classes.items():
+        backend = backend_class()
+
+        if backend.cache_file.exists():
+            content = backend.cache_file.read_text().strip()
+            if content == "None":
+                available = False
+            else:
+                available = True
+                backend._executable_path = content
+        else:
+            try:
+                available = backend.is_available()
+            except Exception:
+                available = False
+
+            if available:
+                backend.cache_file.write_text(backend.required_executable)
+            else:
+                backend.cache_file.write_text("None")
+
+        if available:
+            backends[name] = backend_class
+
+    return backends
+
+
+def search_backends():
+    """
+    Probe all backends directly, ignoring any cache.
+    Updates the cache files with the actual availability.
+    Overwrites existing cache files.
+    """
+    backends.clear()
+
+    for name, backend_class in backend_classes.items():
+        backend = backend_class()
+
+        try:
+            available = backend.is_available()
+        except Exception:
+            available = False
+
+        if available:
+            backend.cache_file.write_text(backend.required_executable)
+            backends[name] = backend_class
+        else:
+            backend.cache_file.write_text("None")
+
+    if backends:
+        Log.success(f"Found backends: {', '.join(backends.keys())}")
+    else:
+        Log.warning("No backends found. Please install pi_fm_rds or fm_transmitter")
+
+
+
+def list_backends():
+    """List every cached backend avalible
+    
+    .. note::
+        You can also use the 'python3 -m piwave list' command.
+    """
+    if not backends:
+        Log.warning("No backends available")
+        return {}
+    
+    backend_info = {}
+    for name, backend_class in backends.items():
+        backend = backend_class()
+        min_freq, max_freq = backend.frequency_range
+        rds = "Yes" if backend.supports_rds else "No"
+        backend_info[name] = {
+            'frequency_range': f"{min_freq}-{max_freq}MHz",
+            'rds_support': rds
+        }
+        Log.info(f"{name}: {min_freq}-{max_freq}MHz, RDS: {rds}")
+    
+    return backend_info

piwave/backends/base.py

@@ -0,0 +1,245 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/backend/base.py : backends backbone
+
+from abc import ABC, abstractmethod
+from typing import Optional
+import subprocess
+import os
+import signal
+import shutil
+from pathlib import Path
+
+class BackendError(Exception):
+    pass
+
+class Backend(ABC):    
+    def __init__(self, frequency: float = 90.0, ps: str = "PiWave", 
+                 rt: str = "", pi: str = "FFFF"):
+        self.frequency = frequency
+        self.ps = ps[:8]  # Max 8 chars
+        self.rt = rt[:64]  # Max 64 chars
+        self.pi = pi[:4]   # Max 4 chars
+        self.current_process: Optional[subprocess.Popen] = None
+        self.is_available_cached: Optional[bool] = None
+        self._executable_path: Optional[str] = None
+    
+    @property
+    @abstractmethod
+    def name(self):
+        pass
+    
+    @property
+    @abstractmethod
+    def frequency_range(self):
+        pass
+    
+    @property
+    @abstractmethod  
+    def supports_rds(self):
+        pass
+
+    @property
+    @abstractmethod
+    def supports_live_streaming(self):
+        pass
+    
+    @property 
+    def cache_file(self):
+        return Path(__file__).parent.parent / f"{self.name}_path"
+    
+    @property
+    def required_executable(self):
+        if self._executable_path:
+            return self._executable_path
+            
+        self._executable_path = self._find_executable()
+        return self._executable_path
+    
+    def _find_executable(self) -> str:
+        # Check cache first
+        if self.cache_file.exists():
+            try:
+                cached_path = self.cache_file.read_text().strip()
+                if self._is_valid_executable(cached_path):
+                    return cached_path
+                else:
+                    self.cache_file.unlink()
+            except Exception:
+                self.cache_file.unlink(missing_ok=True)
+        
+        # Only then search for it
+        found_path = self._search_executable()
+        if found_path:
+            try:
+                self.cache_file.write_text(found_path)
+            except Exception:
+                pass
+            return found_path
+        
+        raise BackendError(f"Could not find path for {self.name}. Please manually add one with python3 -m piwave add {self.name} <path>")
+    
+    @abstractmethod
+    def _get_executable_name(self):
+        pass
+    
+    @abstractmethod  
+    def _get_search_paths(self):
+        pass
+    
+    def _search_executable(self):
+        executable_name = self._get_executable_name()
+        
+        # Try at first system $PATH
+        system_path = shutil.which(executable_name)
+        if system_path and self._is_valid_executable(system_path):
+            return system_path
+        
+        # Then for the dirs
+        search_paths = self._get_search_paths()
+        
+        for search_path in search_paths:
+            if not Path(search_path).exists():
+                continue
+                
+            try:
+                for root, dirs, files in os.walk(search_path):
+                    if executable_name in files:
+                        executable_path = Path(root) / executable_name
+                        if self._is_valid_executable(str(executable_path)):
+                            return str(executable_path)
+            except (PermissionError, OSError):
+                continue
+        
+        return None
+    
+    # valid executable part start
+
+    def _is_valid_executable(self, path: str) -> bool:
+        
+        path_obj = Path(path)
+        if not (path_obj.exists() and path_obj.is_file() and os.access(path, os.X_OK)):
+            return False
+        
+        # test any approach, if only one is valid, its ok
+        validation_methods = [
+            self._ve_try_help_flag,
+            self._ve_try_version_flag,
+            self._ve_try_no_args,
+            self._ve_try_invalid_flag
+        ]
+        
+        for method in validation_methods:
+            try:
+                if method(path):
+                    return True
+            except Exception:
+                continue
+        
+        return False
+    
+    def _ve_try_help_flag(self, path: str) -> bool:
+        try:
+            result = subprocess.run(
+                [path, "--help"], 
+                stdout=subprocess.PIPE, 
+                stderr=subprocess.PIPE, 
+                timeout=3
+            )
+
+            return result.returncode in [0, 1, 2]
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return False
+    
+    def _ve_try_version_flag(self, path: str) -> bool:
+        for flag in ["--version", "-v", "-V"]:
+            try:
+                result = subprocess.run(
+                    [path, flag], 
+                    stdout=subprocess.PIPE, 
+                    stderr=subprocess.PIPE, 
+                    timeout=3
+                )
+                if result.returncode in [0, 1]:
+                    return True
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                continue
+        return False
+    
+    def _ve_try_no_args(self, path: str) -> bool:
+        try:
+            result = subprocess.run(
+                [path], 
+                stdout=subprocess.PIPE, 
+                stderr=subprocess.PIPE, 
+                timeout=1
+            )
+            return True
+        except subprocess.TimeoutExpired:
+            return True
+        except (FileNotFoundError, PermissionError):
+            return False
+    
+    def _ve_try_invalid_flag(self, path: str) -> bool:
+        try:
+            result = subprocess.run(
+                [path, "--piwave-test-invalid-flag"], 
+                stdout=subprocess.PIPE, 
+                stderr=subprocess.PIPE, 
+                timeout=3
+            )
+            return result.returncode in [1, 2]
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return False
+        
+    # valid executable part end
+
+
+    def is_available(self):
+        if self.is_available_cached is not None:
+            return self.is_available_cached
+            
+        try:
+            self.required_executable
+            self.is_available_cached = True
+            return True
+        except BackendError:
+            self.is_available_cached = False
+            return False
+    
+    @abstractmethod
+    def build_command(self, wav_file: str):
+        pass
+
+    @abstractmethod
+    def build_live_command(self):
+        pass
+    
+    def validate_settings(self):
+        min_freq, max_freq = self.frequency_range
+        return min_freq <= self.frequency <= max_freq
+    
+    def play_file(self, wav_file: str) -> subprocess.Popen:
+        if not self.validate_settings():
+            min_freq, max_freq = self.frequency_range
+            raise BackendError(f"{self.name} supports {min_freq}-{max_freq}MHz, got {self.frequency}MHz")
+            
+        cmd = self.build_command(wav_file)
+        self.current_process = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            preexec_fn=os.setsid
+        )
+        return self.current_process
+    
+    def stop(self):
+        if self.current_process:
+            try:
+                os.killpg(os.getpgid(self.current_process.pid), signal.SIGTERM)
+                self.current_process.wait(timeout=5)
+            except (ProcessLookupError, subprocess.TimeoutExpired):
+                try:
+                    os.killpg(os.getpgid(self.current_process.pid), signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+            finally:
+                self.current_process = None

piwave/backends/fm_transmitter.py

@@ -0,0 +1,44 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/backends/fm_transmitter.py : fm_transmitter backend, doesn't supports RDS, can broadcast on freqs 1 to 250
+# needs https://github.com/markondej/fm_transmitter installed on the system to work !
+
+from .base import Backend
+
+class FmTransmitterBackend(Backend):
+    
+    @property
+    def name(self):
+        return "fm_transmitter"
+    
+    @property
+    def frequency_range(self):
+        return (1.0, 250.0)  # fm transmitter supports a pretty good range, tho be aware of performance issues
+    
+    @property
+    def supports_rds(self):
+        return False
+    
+    @property
+    def supports_live_streaming(self):
+        return True
+    
+    def _get_executable_name(self):
+        return "fm_transmitter"
+    
+    def _get_search_paths(self):
+        return ["/opt/PiWave/fm_transmitter", "/opt", "/usr/local/bin", "/usr/bin", "/bin", "/home"]
+    
+    def build_command(self, wav_file: str):
+        return [
+            'sudo', self.required_executable,
+            '-f', str(self.frequency),
+            wav_file
+        ]
+    
+    def build_live_command(self):
+        return [
+            'sudo', self.required_executable,
+            '-f', str(self.frequency),
+            '-'
+        ]

piwave/backends/pi_fm_rds.py

@@ -0,0 +1,49 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/backends/pi_fm_rds.py : PiFmRds backend, supports RDS on freqs 80 to 108
+# needs https://github.com/ChristopheJacquet/PiFmRds installed on the system to work !
+
+from .base import Backend, BackendError
+
+class PiFmRdsBackend(Backend):
+    
+    @property
+    def name(self):
+        return "pi_fm_rds"
+    
+    @property
+    def frequency_range(self):
+        return (80.0, 108.0)  # standard fm band with a bit less bcs it still kinda works
+    
+    @property
+    def supports_rds(self):
+        return True
+    
+    @property
+    def supports_live_streaming(self):
+        return False
+    
+    def _get_executable_name(self):
+        return "pi_fm_rds"
+    
+    def _get_search_paths(self):
+        return ["/opt/PiWave/PiFmRds", "/opt", "/usr/local/bin", "/usr/bin", "/bin", "/home"]
+    
+    def build_command(self, wav_file: str) -> list:
+        cmd = [
+            'sudo', self.required_executable,
+            '-freq', str(self.frequency),
+            '-audio', wav_file
+        ]
+        
+        if self.ps:
+            cmd.extend(['-ps', self.ps])
+        if self.rt:
+            cmd.extend(['-rt', self.rt])
+        if self.pi:
+            cmd.extend(['-pi', self.pi])
+            
+        return cmd
+
+    def build_live_command(self):
+        return None # not supported sadly

piwave/logger.py

@@ -0,0 +1,99 @@
+# PiWave is available at https://piwave.xyz
+# Licensed under GPLv3.0, main GitHub repository at https://github.com/douxxtech/piwave/
+# piwave/Logger.py : Main logging manager
+
+import sys
+
+class Log:
+    COLORS = { # absolutely not taken from stackoverflow trust
+        'reset': '\033[0m',
+        'bold': '\033[1m',
+        'underline': '\033[4m',
+        'red': '\033[31m',
+        'green': '\033[32m',
+        'yellow': '\033[33m',
+        'blue': '\033[34m',
+        'magenta': '\033[35m',
+        'cyan': '\033[36m',
+        'white': '\033[37m',
+        'bright_red': '\033[91m',
+        'bright_green': '\033[92m',
+        'bright_yellow': '\033[93m',
+        'bright_blue': '\033[94m',
+        'bright_magenta': '\033[95m',
+        'bright_cyan': '\033[96m',
+        'bright_white': '\033[97m',
+    }
+
+    ICONS = {
+        'success': 'OK',
+        'error': 'ERR',
+        'warning': 'WARN',
+        'info': 'INFO',
+        'client': 'CLIENT',
+        'server': 'SERVER',
+        'file': 'FILE',
+        'broadcast': 'BCAST',
+        'version': 'VER',
+        'update': 'UPD',
+    }
+
+    SILENT = False
+
+    @classmethod
+    def config(cls, silent: bool = False):
+        cls.SILENT = silent
+
+    @classmethod
+    def print(cls, message: str, style: str = '', icon: str = '', end: str = '\n'):
+
+        if cls.SILENT: return
+
+        color = cls.COLORS.get(style, '')
+        icon_char = cls.ICONS.get(icon, '')
+        if icon_char:
+            if color:
+                print(f"{color}[{icon_char}]\033[0m {message}", end=end)
+            else:
+                print(f"[{icon_char}] {message}", end=end)
+        else:
+            if color:
+                print(f"{color}{message}\033[0m", end=end)
+            else:
+                print(f"{message}", end=end)
+        sys.stdout.flush()
+
+    @classmethod
+    def header(cls, text: str):
+        cls.print(text, 'bright_blue', end='\n\n')
+        sys.stdout.flush()
+
+    @classmethod
+    def section(cls, text: str):
+        cls.print(f" {text} ", 'bright_blue', end='')
+        cls.print("─" * (len(text) + 2), 'blue', end='\n\n')
+        sys.stdout.flush()
+
+    @classmethod
+    def success(cls, message: str):
+        cls.print(message, 'bright_green', 'success')
+
+    @classmethod
+    def error(cls, message: str):
+        cls.print(message, 'bright_red', 'error')
+
+    @classmethod
+    def warning(cls, message: str):
+        cls.print(message, 'bright_yellow', 'warning')
+
+    @classmethod
+    def info(cls, message: str):
+        cls.print(message, 'bright_cyan', 'info')
+
+    @classmethod
+    def file_message(cls, message: str):
+        cls.print(message, 'yellow', 'file')
+
+    @classmethod
+    def broadcast_message(cls, message: str):
+        cls.print(message, 'bright_magenta', 'broadcast')