Download Audio

A Python utility tool to download and play MP3 pronunciations of words and phrases directly from Google TTS. It supports batch processing from text files, direct command-line strings, and StarDict index dictionaries.

Installation

Install from PyPI once the package is published:

pip install download-audio

Or install locally from source during development:

pip install .

Prerequisites: System Audio Player

To enable audio playback, your system must have one of the following command-line media players installed:

• ffplay (part of FFmpeg — recommended)
• mpv
• afplay (built into macOS)
• aplay (Linux ALSA)
• cvlc (VLC headless)

On Ubuntu/Debian, install FFmpeg (which provides ffplay) with:

sudo apt update && sudo apt install ffmpeg

Features

• Smart Caching & Auto-Play: Checks whether an MP3 already exists. By default, it plays pronunciations whether freshly downloaded or retrieved from the local cache.
• Dynamic Directory Creation: Automatically creates a local ./audio/ directory, organized alphabetically into folders A through Z.
• StarDict Support: Parses .idx files from StarDict dictionary folders to extract and download audio for entire dictionaries.
• Text File Batching: Reads words line-by-line or separated by spaces or commas from .txt files.
• Smart Input Resolution: Recognizes inline words without requiring extra file flags or redundant prompts.
• Alphabetical Ordering: Supports normal A–Z or reverse Z–A processing.

Positional Arguments

• source
  • Path to a StarDict folder (containing a .idx index file), a .txt file, or a direct inline word/phrase.
  • If omitted, the script launches an interactive prompt.

Optional Arguments

• -h, --help
  • Show the help message and exit.
• -f TXT_FILE, --file TXT_FILE
  • Path to a text file containing words to download/play.
• -w INLINE_WORDS, --words INLINE_WORDS
  • Inline string of specific word(s) or phrase(s) to process.
• -p [PLAY_OPTION], --play [PLAY_OPTION]
  • Play audio pronunciations exclusively.
• --no-play
  • Skip audio playback during downloads or cache hits (download files without playing sound).
• -r, --reverse
  • Process words in reverse alphabetical order (Z to A).
• --dir CUSTOM_DIR
  • Custom directory path for audio storage (defaults to ./audio).

Usage Examples

1. Interactive Mode (Default Auto-Play)

Run the command without arguments to launch the interactive prompt. Enter a word or path to download and play it immediately:

download-audio

2. Direct Inline Word / Phrase Playback

Pass a word or phrase directly as an argument to download and play it immediately:

download-audio "hello world"

3. Download from a StarDict Directory

Extract keywords from a StarDict dictionary's .idx file, download missing audio files, and organize them into ./audio/:

download-audio /path/to/stardict_folder

4. Batch Process a Text File (Without Audio Playback)

Process a word list to populate the local cache without playing audio:

download-audio words.txt --no-play

5. Reverse Alphabetical Processing (Z to A)

Process a word list in reverse alphabetical order:

download-audio words.txt --reverse

License

Distributed under the MIT License. See LICENSE for more information.