thai-talking-clock 1.0.0__tar.gz

thai_talking_clock-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+graft mp3-thai-clock
+include README.md
+include pyproject.toml
+include test_talking_clock.py
+include example.py
+recursive-include talking_clock *.py

thai_talking_clock-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: thai-talking-clock
+Version: 1.0.0
+Summary: A cross-platform Python library for audio time announcement using MP3 files.
+Author: Billy
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# Thai Talking Clock Python Library (`thai-talking-clock`)
+
+A cross-platform Python library and test suite for a **Talking Clock** that evaluates time as integer hours, minutes, and seconds, builds the corresponding MP3 playback sequence, and auto-detects system commands to play audio on **macOS**, **Linux**, and **Windows**.
+
+```bash
+pip install thai-talking-clock
+```
+
+---
+
+## 🎵 How It Works
+
+1. Evaluates hour, minute, and second as integers (e.g. `09:05:07` -> `hour = 9`, `minute = 5`, `second = 7`).
+2. Generates the exact MP3 playback sequence using the pattern:
+   $$\text{begintime.mp3} \rightarrow \text{\{hour\}.mp3} \rightarrow \text{hour.mp3} \rightarrow \text{\{minute\}.mp3} \rightarrow \text{minute.mp3} \rightarrow \text{\{second\}.mp3} \rightarrow \text{second.mp3} \rightarrow \text{endtime.mp3}$$
+
+   **Example for `09:05:07`:**
+   `begintime.mp3` $\rightarrow$ `9.mp3` $\rightarrow$ `hour.mp3` $\rightarrow$ `5.mp3` $\rightarrow$ `minute.mp3` $\rightarrow$ `7.mp3` $\rightarrow$ `second.mp3` $\rightarrow$ `endtime.mp3`
+
+3. Auto-detects available system audio players across OS platforms using `shutil.which`.
+
+---
+
+## 💻 Supported OS Audio Players
+
+| Operating System | Supported System Commands (in auto-detection priority) |
+| :--- | :--- |
+| **macOS (`darwin`)** | `afplay` (native), `ffplay`, `mpv`, `vlc`, `cvlc` |
+| **Linux** | `play` (SoX), `paplay` (PulseAudio), `mpg123`, `mpg321`, `ffplay`, `mpv`, `cvlc`, `vlc`, `aplay` |
+| **Windows (`win32` / `nt`)** | `powershell` (WMPlayer COM / SoundPlayer), `cmd` (`cmd /c start /wait`), `wmplayer`, `ffplay`, `mpv`, `vlc` |
+
+---
+
+## 📁 Repository Structure
+
+```
+talking-clock/
+├── mp3-thai-clock/      # 65 MP3 files (0.mp3 - 59.mp3, begintime.mp3, endtime.mp3, hour.mp3, minute.mp3, second.mp3)
+├── talking_clock/       # Core Python Library Package
+│   ├── __init__.py      # Package export and convenience function
+│   ├── clock.py         # TalkingClock class (time sequence builder & audio trigger)
+│   ├── player.py        # SystemAudioPlayer class (cross-platform OS player detector)
+│   └── exceptions.py    # Custom exception classes
+├── tests/               # Automated unit tests
+│   ├── test_clock.py    # Unit tests for clock sequence & pattern verification
+│   └── test_player.py   # Unit tests for OS player detection & mock execution
+├── test_talking_clock.py# Main CLI test runner & interactive test tool
+├── example.py           # Simple code example
+└── pyproject.toml       # Python packaging definition
+```
+
+---
+
+## 🚀 Quick Usage
+
+### Python Code Usage
+
+```python
+from talking_clock import TalkingClock, announce_current_time
+
+# 1. Announce current system time immediately
+announce_current_time()
+
+# 2. Or instantiate TalkingClock for custom time announcements
+clock = TalkingClock(mp3_dir="mp3-thai-clock")
+
+# Get audio file sequence for 09:05:07
+seq = clock.get_sequence_for_time(hour=9, minute=5, second=7)
+print(seq)
+
+# Play audio for 09:05:07
+clock.announce_time(hour=9, minute=5, second=7)
+```
+
+---
+
+## 🧪 Running Tests & Command-Line Options
+
+Run the test suite and CLI runner using `test_talking_clock.py`:
+
+```bash
+# 1. Run all unit tests and test example 09:05:07 time announcement:
+python3 test_talking_clock.py
+
+# 2. Run unit tests only:
+python3 test_talking_clock.py --unit
+
+# 3. Dry-run test for specific time (09:05:07):
+python3 test_talking_clock.py --time 09:05:07 --dry-run
+
+# 4. List detected system audio player & OS candidates:
+python3 test_talking_clock.py --list-players
+
+# 5. Verify all 65 required MP3 files exist in mp3-thai-clock:
+python3 test_talking_clock.py --verify
+
+# 6. Announce current system time:
+python3 test_talking_clock.py --now
+```
+
+---
+
+## 📜 Audio Licensing & Commercial Use
+
+> [!NOTE]
+> The MP3 voice audio files located in the `mp3-thai-clock/` directory were generated using **Microsoft Azure Text-to-Speech (Azure Cognitive Services Speech)** using a free subscription token from an Azure subscription.
+> 
+> - **Licensing & Commercial Use**: Audio assets synthesized via Azure Text-to-Speech are subject to the [Microsoft Azure Legal Terms](https://azure.microsoft.com/en-us/support/legal/) and [Azure Cognitive Services Terms](https://azure.microsoft.com/en-us/support/legal/cognitive-services-terms/).
+> - If you plan to use this library or the provided audio files for commercial purposes, please ensure your usage aligns with Microsoft Azure's licensing guidelines or replace the MP3 files with your own custom or commercially licensed voice samples.
+

thai_talking_clock-1.0.0/README.md

@@ -0,0 +1,110 @@
+# Thai Talking Clock Python Library (`thai-talking-clock`)
+
+A cross-platform Python library and test suite for a **Talking Clock** that evaluates time as integer hours, minutes, and seconds, builds the corresponding MP3 playback sequence, and auto-detects system commands to play audio on **macOS**, **Linux**, and **Windows**.
+
+```bash
+pip install thai-talking-clock
+```
+
+---
+
+## 🎵 How It Works
+
+1. Evaluates hour, minute, and second as integers (e.g. `09:05:07` -> `hour = 9`, `minute = 5`, `second = 7`).
+2. Generates the exact MP3 playback sequence using the pattern:
+   $$\text{begintime.mp3} \rightarrow \text{\{hour\}.mp3} \rightarrow \text{hour.mp3} \rightarrow \text{\{minute\}.mp3} \rightarrow \text{minute.mp3} \rightarrow \text{\{second\}.mp3} \rightarrow \text{second.mp3} \rightarrow \text{endtime.mp3}$$
+
+   **Example for `09:05:07`:**
+   `begintime.mp3` $\rightarrow$ `9.mp3` $\rightarrow$ `hour.mp3` $\rightarrow$ `5.mp3` $\rightarrow$ `minute.mp3` $\rightarrow$ `7.mp3` $\rightarrow$ `second.mp3` $\rightarrow$ `endtime.mp3`
+
+3. Auto-detects available system audio players across OS platforms using `shutil.which`.
+
+---
+
+## 💻 Supported OS Audio Players
+
+| Operating System | Supported System Commands (in auto-detection priority) |
+| :--- | :--- |
+| **macOS (`darwin`)** | `afplay` (native), `ffplay`, `mpv`, `vlc`, `cvlc` |
+| **Linux** | `play` (SoX), `paplay` (PulseAudio), `mpg123`, `mpg321`, `ffplay`, `mpv`, `cvlc`, `vlc`, `aplay` |
+| **Windows (`win32` / `nt`)** | `powershell` (WMPlayer COM / SoundPlayer), `cmd` (`cmd /c start /wait`), `wmplayer`, `ffplay`, `mpv`, `vlc` |
+
+---
+
+## 📁 Repository Structure
+
+```
+talking-clock/
+├── mp3-thai-clock/      # 65 MP3 files (0.mp3 - 59.mp3, begintime.mp3, endtime.mp3, hour.mp3, minute.mp3, second.mp3)
+├── talking_clock/       # Core Python Library Package
+│   ├── __init__.py      # Package export and convenience function
+│   ├── clock.py         # TalkingClock class (time sequence builder & audio trigger)
+│   ├── player.py        # SystemAudioPlayer class (cross-platform OS player detector)
+│   └── exceptions.py    # Custom exception classes
+├── tests/               # Automated unit tests
+│   ├── test_clock.py    # Unit tests for clock sequence & pattern verification
+│   └── test_player.py   # Unit tests for OS player detection & mock execution
+├── test_talking_clock.py# Main CLI test runner & interactive test tool
+├── example.py           # Simple code example
+└── pyproject.toml       # Python packaging definition
+```
+
+---
+
+## 🚀 Quick Usage
+
+### Python Code Usage
+
+```python
+from talking_clock import TalkingClock, announce_current_time
+
+# 1. Announce current system time immediately
+announce_current_time()
+
+# 2. Or instantiate TalkingClock for custom time announcements
+clock = TalkingClock(mp3_dir="mp3-thai-clock")
+
+# Get audio file sequence for 09:05:07
+seq = clock.get_sequence_for_time(hour=9, minute=5, second=7)
+print(seq)
+
+# Play audio for 09:05:07
+clock.announce_time(hour=9, minute=5, second=7)
+```
+
+---
+
+## 🧪 Running Tests & Command-Line Options
+
+Run the test suite and CLI runner using `test_talking_clock.py`:
+
+```bash
+# 1. Run all unit tests and test example 09:05:07 time announcement:
+python3 test_talking_clock.py
+
+# 2. Run unit tests only:
+python3 test_talking_clock.py --unit
+
+# 3. Dry-run test for specific time (09:05:07):
+python3 test_talking_clock.py --time 09:05:07 --dry-run
+
+# 4. List detected system audio player & OS candidates:
+python3 test_talking_clock.py --list-players
+
+# 5. Verify all 65 required MP3 files exist in mp3-thai-clock:
+python3 test_talking_clock.py --verify
+
+# 6. Announce current system time:
+python3 test_talking_clock.py --now
+```
+
+---
+
+## 📜 Audio Licensing & Commercial Use
+
+> [!NOTE]
+> The MP3 voice audio files located in the `mp3-thai-clock/` directory were generated using **Microsoft Azure Text-to-Speech (Azure Cognitive Services Speech)** using a free subscription token from an Azure subscription.
+> 
+> - **Licensing & Commercial Use**: Audio assets synthesized via Azure Text-to-Speech are subject to the [Microsoft Azure Legal Terms](https://azure.microsoft.com/en-us/support/legal/) and [Azure Cognitive Services Terms](https://azure.microsoft.com/en-us/support/legal/cognitive-services-terms/).
+> - If you plan to use this library or the provided audio files for commercial purposes, please ensure your usage aligns with Microsoft Azure's licensing guidelines or replace the MP3 files with your own custom or commercially licensed voice samples.
+

thai_talking_clock-1.0.0/example.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Example script showing how to use the talking_clock Python library."""
+
+from talking_clock import TalkingClock, SystemAudioPlayer, announce_current_time
+
+def main():
+    print("--- Talking Clock Library Usage Example ---\n")
+
+    # 1. Quick convenience function to announce current time:
+    # announce_current_time()
+
+    # 2. Instantiate clock with auto-detected player:
+    clock = TalkingClock(mp3_dir="mp3-thai-clock")
+
+    # Display detected player info:
+    player_info = clock.player.detected_player
+    print(f"Detected OS Audio Player: {player_info['name']} ({player_info['binary']})")
+
+    # 3. Generate MP3 sequence for 09:05:07
+    h, m, s = 9, 5, 7
+    seq = clock.get_sequence_for_time(h, m, s)
+
+    print(f"\nSequence for {h:02d}:{m:02d}:{s:02d}:")
+    for f in seq:
+        print(f"  - {f}")
+
+    # 4. Announce custom time
+    print("\nAnnouncing 09:05:07...")
+    clock.announce_time(hour=9, minute=5, second=7, blocking=True)
+    print("Done!")
+
+if __name__ == "__main__":
+    main()

thai_talking_clock-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thai-talking-clock"
+version = "1.0.0"
+description = "A cross-platform Python library for audio time announcement using MP3 files."
+readme = "README.md"
+requires-python = ">=3.7"
+authors = [
+    { name = "Billy" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+]
+dependencies = []
+
+[project.scripts]
+thai-talking-clock = "test_talking_clock:main"
+talking-clock = "test_talking_clock:main"
+
+[tool.setuptools]
+packages = ["talking_clock", "mp3-thai-clock"]
+
+[tool.setuptools.package-data]
+"*" = ["*.mp3"]
+

thai_talking_clock-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thai_talking_clock-1.0.0/talking_clock/__init__.py

@@ -0,0 +1,35 @@
+"""Talking Clock package.
+
+A cross-platform Python library for audio time announcement.
+"""
+
+from .clock import TalkingClock
+from .player import SystemAudioPlayer
+from .exceptions import (
+    TalkingClockError,
+    AudioPlayerNotFoundError,
+    AudioPlaybackError,
+    MissingAudioFileError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "TalkingClock",
+    "SystemAudioPlayer",
+    "TalkingClockError",
+    "AudioPlayerNotFoundError",
+    "AudioPlaybackError",
+    "MissingAudioFileError",
+]
+
+
+def announce_current_time(
+    mp3_dir: str = None,
+    preferred_player: str = None,
+    blocking: bool = True,
+):
+    """Convenience function to announce the current system time immediately."""
+    player = SystemAudioPlayer(preferred_player=preferred_player)
+    clock = TalkingClock(mp3_dir=mp3_dir, player=player)
+    return clock.announce_time(blocking=blocking)