# Google Pronouncer
A Python library for downloading pronunciation MP3 files from Google's dictionary service.
## Installation
```bash
pip install google-pronouncer
```
## Command Line Usage
The package provides a simple command-line interface:
### Download Pronunciations
```bash
# Download US pronunciation (default) - saves in current directory
google-pronouncer -d hello world
# Download British pronunciation
google-pronouncer -d hello -a gb
# Download both accents (automatically uses subdirectories)
google-pronouncer -d hello -a all
# Save files in a specific directory
google-pronouncer -d hello -o ./pronunciations
# Force using subdirectories even for single accent
google-pronouncer -d hello --use-subdirs
# Download from a file (one word per line)
google-pronouncer -f words.txt
# Force fresh download (ignore cache)
google-pronouncer -d hello --force-download
# Disable cache usage
google-pronouncer -d hello --no-cache
# Download with verbose logging
google-pronouncer -v -d hello world
```
### File Organization
By default:
- Files are saved in the current directory
- Single accent downloads: Saved as `word_accent.mp3`
- Multiple accent downloads: Organized in subdirectories as `word/word_accent.mp3`
- Use `-o` to specify a different output directory
- Use `--use-subdirs` to force subdirectory organization even for single accent downloads
### Cache Management
```bash
# Show cache information for all words
google-pronouncer cache-info
# Show cache info for specific words
google-pronouncer cache-info hello world
# Clear all cache
google-pronouncer clear-cache
# Clear cache for specific words
google-pronouncer clear-cache hello world
```
### Global Options
```bash
-d, --download WORD Download pronunciations for one or more words
-f, --file FILE File containing words to download (one word per line)
-a, --accent {gb,us,all} Accent to download (us=American, gb=British, all=both) (default: us)
-j, --jobs N Number of parallel downloads (default: 4)
-o, --output-dir PATH Directory to save pronunciations (default: ./pronunciations)
-t, --timeout SECONDS Request timeout in seconds (default: 10)
-v, --verbose Enable verbose logging
--no-cache Disable cache usage
--force-download Force download even if cached
--use-subdirs Use subdirectories for each word (default: only when downloading multiple accents)
```
## Python Library Usage
### Basic Usage
```python
from google_pronouncer import GooglePronunciationDownloader, DownloadConfig, AccentType
# Create configuration (files will be saved in current directory)
config = DownloadConfig(
output_dir=".", # Current directory
use_cache=True, # Enable caching (default: True)
force_download=False # Force fresh download (default: False)
)
# Or specify a different output directory
config = DownloadConfig(
output_dir="./pronunciations",
use_cache=True,
force_download=False
)
# Initialize downloader
downloader = GooglePronunciationDownloader(config)
# Download US pronunciation (default)
path = downloader.download_pronunciation("hello", AccentType.AMERICAN)
print(f"Downloaded to: {path}")
# Download British pronunciation
path = downloader.download_pronunciation("hello", AccentType.BRITISH)
print(f"Downloaded to: {path}")
# Download both accents for a word
paths = downloader.download_all_accents("world")
print(f"Downloaded files: {paths}")
# Download multiple words (US accent by default)
words = ["hello", "world", "python"]
paths = downloader.download_words(words)
print(f"Downloaded files: {paths}")
```
### Cache Management
```python
# Get cache information
info = downloader.get_cache_info() # All words
info = downloader.get_cache_info("hello") # Specific word
# Clear cache
downloader.clear_cache() # All words
downloader.clear_cache("hello") # Specific word
```
### Configuration Options
```python
config = DownloadConfig(
output_dir="pronunciations", # Directory to save files
timeout=10, # Request timeout in seconds
user_agent="Custom User Agent", # Optional custom user agent
use_cache=True, # Whether to use cached files
min_file_size=1024, # Minimum valid file size in bytes
force_download=False # Force fresh download
)
```
### Available Accents
- `AccentType.BRITISH` - British English pronunciation (`gb`)
- `AccentType.AMERICAN` - American English pronunciation (`us`)
### Error Handling
```python
from google_pronouncer import DownloadError, CacheError
try:
path = downloader.download_pronunciation("word", AccentType.BRITISH)
except DownloadError as e:
print(f"Download failed: {e}")
except CacheError as e:
print(f"Cache error: {e}")
```
## Features
- Download pronunciations in British and American English
- Configurable output directory and request settings
- Smart caching system with validation
- Cache management tools (info, clear)
- Command-line interface
- Proper error handling and logging
- Type hints for better IDE support
- Support for downloading multiple words and accents
- Clean and simple API
## Cache System
The library includes a smart caching system that:
- Automatically caches downloaded files
- Validates cached files before use
- Provides cache information and management
- Supports forced fresh downloads
- Includes file size validation
- Maintains cache metadata
## Requirements
- Python 3.7+
- requests library (>=2.31.0)
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/HachiroSan/google-pronouncer",
"name": "google-pronouncer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "pronunciation, audio, google, dictionary, text-to-speech, education, language",
"author": "Hachiro",
"author_email": "farhad@farhad.my",
"download_url": "https://files.pythonhosted.org/packages/c4/ee/2c9e115b941bba0c12957e01622b94ad4045f39cd4367bfa3603d917d79f/google_pronouncer-0.3.0.tar.gz",
"platform": null,
"description": "# Google Pronouncer\n\nA Python library for downloading pronunciation MP3 files from Google's dictionary service.\n\n## Installation\n\n```bash\npip install google-pronouncer\n```\n\n## Command Line Usage\n\nThe package provides a simple command-line interface:\n\n### Download Pronunciations\n\n```bash\n# Download US pronunciation (default) - saves in current directory\ngoogle-pronouncer -d hello world\n\n# Download British pronunciation\ngoogle-pronouncer -d hello -a gb\n\n# Download both accents (automatically uses subdirectories)\ngoogle-pronouncer -d hello -a all\n\n# Save files in a specific directory\ngoogle-pronouncer -d hello -o ./pronunciations\n\n# Force using subdirectories even for single accent\ngoogle-pronouncer -d hello --use-subdirs\n\n# Download from a file (one word per line)\ngoogle-pronouncer -f words.txt\n\n# Force fresh download (ignore cache)\ngoogle-pronouncer -d hello --force-download\n\n# Disable cache usage\ngoogle-pronouncer -d hello --no-cache\n\n# Download with verbose logging\ngoogle-pronouncer -v -d hello world\n```\n\n### File Organization\n\nBy default:\n- Files are saved in the current directory\n- Single accent downloads: Saved as `word_accent.mp3`\n- Multiple accent downloads: Organized in subdirectories as `word/word_accent.mp3`\n- Use `-o` to specify a different output directory\n- Use `--use-subdirs` to force subdirectory organization even for single accent downloads\n\n### Cache Management\n\n```bash\n# Show cache information for all words\ngoogle-pronouncer cache-info\n\n# Show cache info for specific words\ngoogle-pronouncer cache-info hello world\n\n# Clear all cache\ngoogle-pronouncer clear-cache\n\n# Clear cache for specific words\ngoogle-pronouncer clear-cache hello world\n```\n\n### Global Options\n\n```bash\n -d, --download WORD Download pronunciations for one or more words\n -f, --file FILE File containing words to download (one word per line)\n -a, --accent {gb,us,all} Accent to download (us=American, gb=British, all=both) (default: us)\n -j, --jobs N Number of parallel downloads (default: 4)\n -o, --output-dir PATH Directory to save pronunciations (default: ./pronunciations)\n -t, --timeout SECONDS Request timeout in seconds (default: 10)\n -v, --verbose Enable verbose logging\n --no-cache Disable cache usage\n --force-download Force download even if cached\n --use-subdirs Use subdirectories for each word (default: only when downloading multiple accents)\n```\n\n## Python Library Usage\n\n### Basic Usage\n\n```python\nfrom google_pronouncer import GooglePronunciationDownloader, DownloadConfig, AccentType\n\n# Create configuration (files will be saved in current directory)\nconfig = DownloadConfig(\n output_dir=\".\", # Current directory\n use_cache=True, # Enable caching (default: True)\n force_download=False # Force fresh download (default: False)\n)\n\n# Or specify a different output directory\nconfig = DownloadConfig(\n output_dir=\"./pronunciations\",\n use_cache=True,\n force_download=False\n)\n\n# Initialize downloader\ndownloader = GooglePronunciationDownloader(config)\n\n# Download US pronunciation (default)\npath = downloader.download_pronunciation(\"hello\", AccentType.AMERICAN)\nprint(f\"Downloaded to: {path}\")\n\n# Download British pronunciation\npath = downloader.download_pronunciation(\"hello\", AccentType.BRITISH)\nprint(f\"Downloaded to: {path}\")\n\n# Download both accents for a word\npaths = downloader.download_all_accents(\"world\")\nprint(f\"Downloaded files: {paths}\")\n\n# Download multiple words (US accent by default)\nwords = [\"hello\", \"world\", \"python\"]\npaths = downloader.download_words(words)\nprint(f\"Downloaded files: {paths}\")\n```\n\n### Cache Management\n\n```python\n# Get cache information\ninfo = downloader.get_cache_info() # All words\ninfo = downloader.get_cache_info(\"hello\") # Specific word\n\n# Clear cache\ndownloader.clear_cache() # All words\ndownloader.clear_cache(\"hello\") # Specific word\n```\n\n### Configuration Options\n\n```python\nconfig = DownloadConfig(\n output_dir=\"pronunciations\", # Directory to save files\n timeout=10, # Request timeout in seconds\n user_agent=\"Custom User Agent\", # Optional custom user agent\n use_cache=True, # Whether to use cached files\n min_file_size=1024, # Minimum valid file size in bytes\n force_download=False # Force fresh download\n)\n```\n\n### Available Accents\n\n- `AccentType.BRITISH` - British English pronunciation (`gb`)\n- `AccentType.AMERICAN` - American English pronunciation (`us`)\n\n### Error Handling\n\n```python\nfrom google_pronouncer import DownloadError, CacheError\n\ntry:\n path = downloader.download_pronunciation(\"word\", AccentType.BRITISH)\nexcept DownloadError as e:\n print(f\"Download failed: {e}\")\nexcept CacheError as e:\n print(f\"Cache error: {e}\")\n```\n\n## Features\n\n- Download pronunciations in British and American English\n- Configurable output directory and request settings\n- Smart caching system with validation\n- Cache management tools (info, clear)\n- Command-line interface\n- Proper error handling and logging\n- Type hints for better IDE support\n- Support for downloading multiple words and accents\n- Clean and simple API\n\n## Cache System\n\nThe library includes a smart caching system that:\n- Automatically caches downloaded files\n- Validates cached files before use\n- Provides cache information and management\n- Supports forced fresh downloads\n- Includes file size validation\n- Maintains cache metadata\n\n## Requirements\n\n- Python 3.7+\n- requests library (>=2.31.0)\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details. \n",
"bugtrack_url": null,
"license": null,
"summary": "A library for downloading pronunciation MP3 files from Google's dictionary service",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/HachiroSan/google-pronouncer/issues",
"Documentation": "https://github.com/HachiroSan/google-pronouncer#readme",
"Homepage": "https://github.com/HachiroSan/google-pronouncer"
},
"split_keywords": [
"pronunciation",
" audio",
" google",
" dictionary",
" text-to-speech",
" education",
" language"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15eeb97a2b8fbc726b08f7d8df588165d07fbb73a3a9afe20b9a4b16aa0d261a",
"md5": "e48f9fefb23bd201510e5b78aa7a37a2",
"sha256": "2299362c41818461227a0f905e6f121faae7cfe4794d755eda492913a7555b2d"
},
"downloads": -1,
"filename": "google_pronouncer-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e48f9fefb23bd201510e5b78aa7a37a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10751,
"upload_time": "2025-01-29T15:22:17",
"upload_time_iso_8601": "2025-01-29T15:22:17.947314Z",
"url": "https://files.pythonhosted.org/packages/15/ee/b97a2b8fbc726b08f7d8df588165d07fbb73a3a9afe20b9a4b16aa0d261a/google_pronouncer-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c4ee2c9e115b941bba0c12957e01622b94ad4045f39cd4367bfa3603d917d79f",
"md5": "880fb2b49fb7e109c2963d5cbb0bd5bb",
"sha256": "0a0eff24d49cba2d8434f84d487f38a99227a7cc2b66dea2e6a240e1e69c9273"
},
"downloads": -1,
"filename": "google_pronouncer-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "880fb2b49fb7e109c2963d5cbb0bd5bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11063,
"upload_time": "2025-01-29T15:22:19",
"upload_time_iso_8601": "2025-01-29T15:22:19.485269Z",
"url": "https://files.pythonhosted.org/packages/c4/ee/2c9e115b941bba0c12957e01622b94ad4045f39cd4367bfa3603d917d79f/google_pronouncer-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-29 15:22:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HachiroSan",
"github_project": "google-pronouncer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "google-pronouncer"
}
JSON
