ayatulkursi 1.0.0__tar.gz

ayatulkursi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ayatul Kursi Project Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ayatulkursi-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include ayatulkursi/assets *

ayatulkursi-1.0.0/PKG-INFO

@@ -0,0 +1,463 @@
+Metadata-Version: 2.4
+Name: ayatulkursi
+Version: 1.0.0
+Summary: Production-ready Python CLI application for playing Ayatul Kursi audio in the background
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/ayatulkursi
+Project-URL: Documentation, https://github.com/yourusername/ayatulkursi#readme
+Project-URL: Repository, https://github.com/yourusername/ayatulkursi.git
+Project-URL: Issues, https://github.com/yourusername/ayatulkursi/issues
+Keywords: ayatul-kursi,audio,player,cli,background
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame>=2.1.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Dynamic: license-file
+
+# Ayatul Kursi Background Player CLI
+
+A production-ready Python CLI application that continuously plays Ayatul Kursi audio in the background with various playback modes and options.
+
+---
+
+## Features
+
+- **🎵 Infinite Loop Playback**: Play Ayatul Kursi continuously forever
+- **⏱️ Timed Playback**: Specify duration in minutes or hours
+- **🤫 Whisper Mode**: Low-volume mode (10%) for background recitation
+- **🔊 Volume Control**: Customize volume from 0.0 to 1.0
+- **🖥️ Background Playback**: Runs in the background without blocking the terminal
+- **🔄 Smooth Transitions**: Seamless looping between audio repetitions
+- **🛑 Graceful Shutdown**: Clean exit with Ctrl+C
+- **🌍 Cross-Platform**: Works on Windows, Linux, and macOS
+- **📝 Detailed Logging**: Optional debug logging for troubleshooting
+- **🎨 User-Friendly Output**: Clear messages and status information
+
+---
+
+## 📋 Requirements
+
+- Python 3.10 or higher
+- pygame (for audio playback)
+- click (for CLI interface)
+
+---
+
+## 🚀 Installation
+
+### Method 1: Install from PyPI (Recommended - Coming Soon)
+
+```bash
+pip install ayatulkursi
+```
+
+### Method 2: Install from Source
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/ayatulkursi.git
+cd ayatulkursi
+```
+
+2. Install the package in development mode:
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+3. Verify installation:
+```bash
+ayatulkursi --help
+```
+
+### Method 3: Local Setup
+
+1. Navigate to the project directory
+2. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Create symbolic link or alias for easy access:
+```bash
+# On Windows
+python -m ayatulkursi.cli --help
+
+# Or add to PATH and run directly
+ayatulkursi --help
+```
+
+---
+
+## 📖 Usage
+
+### Basic Usage
+
+#### Infinite Playback (Default)
+Play Ayatul Kursi continuously forever:
+```bash
+ayatulkursi
+```
+
+**Output:**
+```
+============================================================
+  🎵 Ayatul Kursi - Background Audio Player
+============================================================
+
+📋 Mode: Normal Mode - Volume: 70% - Duration: Infinite
+🎵 Audio: /path/to/audio/ayatul-kursi-saad-al-ghamdi.mp3
+
+💡 Press Ctrl+C to stop playback
+
+✓ Playback started in background
+```
+
+---
+
+#### Timed Playback
+
+**Play for 30 minutes:**
+```bash
+ayatulkursi --minutes 30
+```
+
+**Play for 2 hours:**
+```bash
+ayatulkursi --hours 2
+```
+
+**Play for 1 hour and 30 minutes:**
+```bash
+ayatulkursi --hours 1 --minutes 30
+```
+
+**Output:**
+```
+============================================================
+  🎵 Ayatul Kursi - Background Audio Player
+============================================================
+
+📋 Mode: Normal Mode - Volume: 70% - Duration: 30m
+🎵 Audio: /path/to/audio/ayatul-kursi-saad-al-ghamdi.mp3
+
+💡 Press Ctrl+C to stop playback
+
+✓ Playback started in background
+```
+
+---
+
+### Advanced Options
+
+#### Whisper Mode
+Low-volume mode perfect for continuous background recitation:
+
+```bash
+# Infinite whisper mode
+ayatulkursi --whisper
+
+# Whisper mode for 8 hours
+ayatulkursi --whisper --hours 8
+
+# Whisper mode for 2 hours
+ayatulkursi --whisper --hours 2
+```
+
+**Output:**
+```
+============================================================
+  🎵 Ayatul Kursi - Background Audio Player
+============================================================
+
+📋 Mode: Whisper Mode - Volume: 10% - Duration: 8h 0m
+🎵 Audio: /path/to/audio/ayatul-kursi-saad-al-ghamdi.mp3
+
+💡 Press Ctrl+C to stop playback
+
+🤫 Whisper mode activated - playing at low volume
+✓ Playback started in background
+```
+
+---
+
+#### Custom Volume
+
+Set volume between 0.0 (silent) and 1.0 (maximum):
+
+```bash
+# Very low volume (30%)
+ayatulkursi --volume 0.3
+
+# Medium volume (50%)
+ayatulkursi --volume 0.5
+
+# High volume (90%)
+ayatulkursi --volume 0.9
+
+# With duration
+ayatulkursi --volume 0.4 --hours 2
+```
+
+**Output:**
+```
+============================================================
+  🎵 Ayatul Kursi - Background Audio Player
+============================================================
+
+📋 Mode: Normal Mode - Volume: 30% - Duration: Infinite
+🎵 Audio: /path/to/audio/ayatul-kursi-saad-al-ghamdi.mp3
+
+💡 Press Ctrl+C to stop playback
+
+✓ Playback started in background
+```
+
+---
+
+#### Custom Audio File
+
+Use a different audio file:
+```bash
+ayatulkursi --audio-file /path/to/custom/audio.mp3
+```
+
+---
+
+#### Debug Mode
+
+Enable detailed logging for troubleshooting:
+```bash
+ayatulkursi --debug
+```
+
+---
+
+### Command-Line Options
+
+```
+Options:
+  --minutes INTEGER           Play for specified number of minutes
+  --hours INTEGER             Play for specified number of hours
+  --whisper                   Enable whisper mode (volume 10%)
+  --volume FLOAT              Set volume level (0.0-1.0), default is 0.7
+  --audio-file TEXT           Path to audio file (uses default if not provided)
+  --debug                     Enable debug logging
+  --help                      Show this message and exit
+```
+
+---
+
+## 🎯 Use Cases
+
+### 1. Daily Recitation Routine
+```bash
+# Play for 15 minutes in the morning
+ayatulkursi --minutes 15
+```
+
+### 2. All-Day Background Recitation
+```bash
+# Play continuously with whisper mode
+ayatulkursi --whisper
+```
+
+### 3. Work/Study Sessions
+```bash
+# Play quietly during work
+ayatulkursi --volume 0.3 --whisper --hours 8
+```
+
+### 4. Night-Time Listening
+```bash
+# Low volume for 6 hours before sleep
+ayatulkursi --whisper --hours 6
+```
+
+### 5. Prayer Time Sessions
+```bash
+# Dedicated recitation for 1 hour
+ayatulkursi --hours 1 --volume 0.8
+```
+
+---
+
+## 🤫 Understanding Whisper Mode
+
+Whisper Mode is a special feature designed for continuous, non-intrusive playback:
+
+- **Volume**: Automatically set to 10% (very low)
+- **Duration**: Can be infinite or limited (use `--hours` and `--minutes`)
+- **Purpose**: Background recitation while working, studying, or relaxing
+- **Example**: `ayatulkursi --whisper --hours 8`
+
+### Why Use Whisper Mode?
+
+- ✅ Minimizes distraction while maintaining presence
+- ✅ Ideal for work/study environments
+- ✅ Comfortable for extended listening
+- ✅ Respectful volume for shared spaces
+
+---
+
+## 🔧 Troubleshooting
+
+### Issue: "Audio file not found"
+**Solution**: Ensure the audio file `ayatul-kursi-saad-al-ghamdi.mp3` is located in the `assets/` directory relative to the installation.
+
+```bash
+# Check audio file location
+ls ayatulkursi/assets/
+# Should show: ayatul-kursi-saad-al-ghamdi.mp3
+```
+
+### Issue: "pygame not found" or "ModuleNotFoundError"
+**Solution**: Install required dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+### Issue: Audio cuts off or has crackling
+**Solution**: 
+- Try adjusting volume: `--volume 0.6`
+- Check system audio settings
+- Ensure no other applications are using audio
+- Update pygame: `pip install --upgrade pygame`
+
+### Issue: Command not found after installation
+**Solution**: 
+- Reinstall the package: `pip install -e .`
+- Or run with Python module: `python -m ayatulkursi.cli`
+- Ensure `~/.local/bin` is in your PATH (Linux/macOS)
+
+### Issue: Graceful shutdown not working
+**Solution**:
+- Press Ctrl+C (may need to press twice)
+- On Windows, you can also close the terminal window
+- Check if debug mode provides more information: `--debug`
+
+### Getting Help
+Enable debug mode to see detailed logs:
+```bash
+ayatulkursi --debug
+```
+
+---
+
+## 📦 Project Structure
+
+```
+ayatulkursi/
+├── ayatulkursi/
+│   ├── __init__.py           # Package initialization
+│   ├── cli.py                # Command-line interface
+│   ├── player.py             # Audio player logic
+│   └── config.py             # Configuration management
+├── assets/
+│   └── ayatul-kursi-saad-al-ghamdi.mp3  # Audio file
+├── README.md                 # This file
+├── requirements.txt          # Python dependencies
+├── pyproject.toml            # Project configuration
+└── LICENSE                   # MIT License
+```
+
+---
+
+## 🛠️ Development
+
+### Setting up Development Environment
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/ayatulkursi.git
+cd ayatulkursi
+```
+
+2. Install in development mode with dev dependencies:
+```bash
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+3. Run tests:
+```bash
+pytest
+```
+
+4. Run linting:
+```bash
+black ayatulkursi/
+flake8 ayatulkursi/
+mypy ayatulkursi/
+isort ayatulkursi/
+```
+
+### Code Style
+- Uses Black for code formatting
+- PEP 8 compliant
+- Type hints throughout
+- Comprehensive docstrings
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with [pygame](https://www.pygame.org/) for audio playback
+- CLI powered by [click](https://click.palletsprojects.com/)
+- Ayatul Kursi recitation by Saad Al-Ghamdi
+
+---
+
+## 📞 Support & Feedback
+
+- 🐛 Report bugs: [GitHub Issues](https://github.com/nawaz0x1/ayatulkursi/issues)
+- 💡 Suggest features: [GitHub Discussions](https://github.com/nawaz0x1/ayatulkursi/discussions)
+- 📧 Contact: nawazhaider60@example.com
+
+---
+
+## 🎓 Learn More
+
+### What is Ayatul Kursi?
+
+Ayatul Kursi (Verse of the Throne) is the 255th verse of Surah Al-Baqarah (Chapter 2) in the Quran. It is considered one of the most powerful and important verses in Islam.
+
+This application allows you to continuously listen to beautiful recitations of this verse in the background.
+
+### Recommended Listening Times
+
+- **Morning**: 10-15 minutes after Fajr prayer
+- **Throughout the day**: Use whisper mode while working
+- **Before sleep**: 1-2 hours in whisper mode
+- **During stress**: 30+ minutes at any comfortable volume
+
+---
+
+**Made with ❤️ for spiritual wellness**