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.

Command-Line Arguments & Options

usage: download-audio [-h] [-f TXT_FILE] [-w INLINE_WORDS] [-p [PLAY_OPTION]]
                      [--no-play] [-r] [--dir CUSTOM_DIR] [source]

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

Running the Application

You can run download-audio either as an installed Python package or as a standalone executable downloaded from the project's GitHub Releases.

1. Run the Python Package

After installing the package from PyPI or from the local source directory, run the command directly in your terminal:

# Start interactive mode
download-audio

# Download and play an inline word or phrase
download-audio "hello world"

# Process a StarDict dictionary directory
download-audio /path/to/stardict_folder

If the command is not found after a local installation, check that your Python environment is activated and that the environment's executable directory is on your PATH.

2. Run a Standalone Binary

Download the executable for your operating system from the project's GitHub Releases. Open a terminal in the directory containing the downloaded file.

Linux

For download-audio-linux, grant execute permission and run it:

chmod +x download-audio-linux
./download-audio-linux "hello world"

macOS

For download-audio-macos, grant execute permission and run it:

chmod +x download-audio-macos
./download-audio-macos "hello world"

If macOS Gatekeeper blocks the executable because it is unsigned or cannot verify its developer, only proceed if you trust the binary and its source. Review the warning in System Settings → Privacy & Security and follow the available option to allow it, if appropriate.

Windows

Open PowerShell or Command Prompt in the directory containing download-audio-windows.exe. In PowerShell, run:

.\download-audio-windows.exe "hello world"

In Command Prompt, run:

download-audio-windows.exe "hello world"

Audio Playback Requirements

Standalone packaging does not necessarily include a system audio player. If playback is unavailable, install and configure a supported command-line player such as ffplay (from FFmpeg), mpv, afplay (macOS), aplay (Linux), or cvlc (VLC). See Prerequisites: System Audio Player above.

License

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