Metadata-Version: 2.4
Name: download-audio
Version: 0.1.5
Summary: Download and play MP3 pronunciations from Google TTS.
Author: Sat Naing Tun
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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:

```bash
pip install download-audio
```

Or install locally from source during development:

```bash
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:

```bash
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

```text
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:

```bash
download-audio
```

### 2. Direct Inline Word / Phrase Playback

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

```bash
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/`:

```bash
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:

```bash
download-audio words.txt --no-play
```

### 5. Reverse Alphabetical Processing (Z to A)

Process a word list in reverse alphabetical order:

```bash
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:

```bash
# 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:

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

#### macOS

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

```bash
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:

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

In Command Prompt, run:

```bat
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](#prerequisites-system-audio-player) above.

## License

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