Metadata-Version: 2.4
Name: audiotown
Version: 1.11.6
Summary: Media Library Assistant and Legacy Media Rescuser for Apple Ecosystem 
Author-email: Stephen Wang <holleratme420@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zjgcainiao/audiotown
Project-URL: Repository, https://github.com/zjgcainiao/audiotown.git
Project-URL: Issues, https://github.com/zjgcainiao/audiotown/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3
Requires-Dist: wcwidth>=0.2
Dynamic: license-file

# Audiotown: The High-Performance Media Rescuer

A lightweight, "Shokunin" grade CLI for standardizing your media library. Optimized for moving legacy files into a high-integrity, Apple-compatible collection.

## Performance & Core Features

1. Rapid Library Auditing: Built for scale. Scans ~13,000 files in under 60 seconds.
2. Lossless Audio Migration: Batch-converts .flac to Apple-friendly .m4a using either ALAC (Lossless) or AAC (High Quality).
3. Metadata Integrity: Preserves tags (Artist, Album, Track) and ensures high-resolution artwork is embedded directly into the converted files.
4. Smart Deduplication: Avoids redundant processing by identifying existing compliant files.

## What’s New v1.11.4: The Video Upgrade
The new `--to-video` flag transforms Audiotown from an audio tool into a full-scale Media Library Assistant.
1. Video "Upgrade" Capabilities
   1. Format Normalization: Transcodes legacy AVI, RMVB, and MKV into standardized Apple-safe MP4 containers.
   2. Intelligent Encoding: Uses H.264/AAC or H.265/AAC configurations.
   3. Smart Remuxing: If the source streams are already compliant, Audiotown performs a "Lightning Fast" remux (copy) instead of a full transcode to preserve 100% quality.
   4. 10-bit to 8-bit Correction: Automatically handles the "10-bit H.264" problem by transcoding incompatible yuv420p10le streams to standard 8-bit yuv420p for hardware compatibility.
   5. Legacy Hardware Support: Optimized for maximum compatibility with iPhone 5s and later.
   6. Subtitle Preservation: Detects and converts compatible subtitle streams to mov_text for native playback on Apple devices.

2. 🛠 Improved UX
   1. Polished Terminal Output: Enhanced progress tracking and error reporting.
   2. Refined CLI Logic: Improved handling of edge cases and path-based batching.
3. Quck Start
      ```zsh
      # audios
      audiotown convert '/path/to/audio_folder/' --report-path=/another/path/
      # videos
      audiotown convert '/path/to/video_folder/' --to-video=mp4
      ```
##  Prefer a Native macOS Experience?
1. If you want the power of this workflow in a dedicated desktop environment, check out Audiotown Pro. It is a rugged media rescuer designed specifically for the Apple ecosystem.

2. Why use the Pro version?
   1. _Deep Library Auditing_: Scan your video and audio collections for actionable metrics: health scores, "Direct Play" readiness, codec compliance, and metadata gaps (languages, release years, etc.).
   2. _Lossless Audio Integrity_: Batch-convert FLAC to Apple-compatible M4A using ALAC (Lossless) or AAC. Includes automated high-res artwork embedding.
   3. _Legacy Video Recovery_: Seamlessly move AVI, RMVB, MKV, and MP4 files into Apple-safe formats. Features intelligent subtitle handling (including OCR-ready text conversion) to ensure your legacy media actually plays on modern hardware.
   4. Built for Stamina: Designed to handle thousands of files with the same technical rigor you expect from high-end financial or engineering tools.

3. Get Audiotown Pro on Gumroad
   1. [Learn more about Audiotown Pro at gumRoad](https://holleratme.gumroad.com/l/dclqyl)


# CLI Commands

1. `audiotown` contains three commands: `check`, `stats` and `convert`. This package requires `ffmepg` installed in the system. 
   1. To run them, type `auditown check` or `audio stats` or `audio convert`.
   2. Type `audiotown check` to run `check`. 
   3. The command checks if `ffmpeg` is installed.
2. `stats` acts as an executive assisant for audio media management. Personal media library are often messy. This command starts by searching the `folder` recursively and laser focus ONLY on audio files (filtered by file suffix). It then prints out to the terminal a summary report based on what it finds: 
   1. numbers of songs by formats, by encoder types,
   2. storage usage details, 
   3. what top artists, genres, albums are to me ,
   4. are they lossless or lossy, and 
   5. detect potential unreadable or corrupt files. 
3. `stats` can export scanned records into a JSON via `--report-path` flag. Default value is `.` (current directory).
4. `convert`. It converts all `.flac` files in a folder into lossless (`alac`) or lossy (`aac`) versions. An apple lossless encoded `.m4a` file can be recognized in Apple eco system but not usually for `.flac` files. 
   1. `--report-path` is available in `convert` too. To run it `audiocheck convert /path/to/flacs --encoder=alac --report-path=.`. The converted will be exported to a new folder `audiotown_export` in the same folder `path/to/flacs`. 
   2. `convert` also supports `--dry-run` as a tool to preview changes made in a conversion.
   3. `convert` searches files recursively so I can specify a high-level `folder` like `Media` or `myMediaHub`. Try with one ablum folder first.
   4. `convert` supports `--bitrate` when the `--encoder=aac` is specified. the default bitrate kbps is `256k`. `128k` and `320k` are the other valid inputs.
   5. `convert` by default tries to add artwork into files when converting. It searches for `cover.jpg` or `library.jpg` at the root of the folder. if the source file does not contain an artwork, the command attempts to find such file and embed it into the output whenever possible.
5. `convert` now supports a new video transcode flag `--to-video=mp4`. It tranforms the old AVI files into Apple ready MP4. Output files will be saved under a new subfolder named `audiotown_exported`.


## Demos
- ![flac to m4a](https://raw.githubusercontent.com/zjgcainiao/audiotown/main/docs/demo_convert.png)
- ![stats demo](https://raw.githubusercontent.com/zjgcainiao/audiotown/main/docs/demo_stat.png)
- ![avi upgrade to apple safe mp4 demo](docs/avi-rmvb-convert.png)

# Installation
1. Ensure I have [FFmpeg](https://ffmpeg.org/download.html) installed on the system. It is the powerhouse that does the conversion and other heavy work like probing `ffprobe`. Will need it installed and working. MacOS users can install it via [homebrew](https://formulae.brew.sh/formula/ffmpeg): `brew install ffmpeg`.
2. ![Version](https://img.shields.io/pypi/v/audiotown) ![Python](https://img.shields.io/pypi/pyversions/audiotown) >=3.10. 
3. Requires `click` and `wcwidth` libaries.

```zsh
# [optional but recommended] set up a virutal env named `my_env`.
python3 -m venv my_env
source my_env/bin/activate
# check python version 3.10+
python --version 

# udpate pip
pip install --upgrade pip

pip install audiotown

# help
audiotown
```
# 🛠 Usage

```txt
Usage: audiotown [OPTIONS] COMMAND [ARGS]...
Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  check    Verify that FFmpeg and dependencies are correctly installed.
  convert  Convert FLACs in FOLDER to Apple-friendly formats.
  stats    Stats Dashboard & Insight tool.
```

## Examples

1. The simplest way to use `AudioTown` is to run it in a folder containing FLAC files: `audiotown convert /path/to/album/folder --codec=alac --report-path=/path/to/report/folder --dry-run`. The search is recursive.\[=po-iu9o0[]\
2. . the output files from `audio convert` are under the subfolder `audiotown_export/` within `/path/to/album/folder`.
3. The `/path/to/report/folder` can be `.` or any specified directories.
4. use `--dry-run` to preview any perceived changes.
5. The `convert` takes only `flac` files. It supports: `flac --> alac` or `flac --> aac`.
   1. `--bitrate` can be specified for `flac --> aac` (default: `256k`)

```zsh
# 1. show additional help 
audiotown
audiotown -h
audiotown --help

# 2. check ffmpeg installation
audiotown check

# 3. show stats of a media folder 
cd /path/to/media/folder
audiotown stats . 
# alternatively 
audiotown stats  /path/to/media/folder
audiotown stats  /path/to/media/folder --report-path=.

# enable duplicating searching
audiotown stats  /path/to/media/folder --find-duplicate --report-path=. 

# 4. convert all flac files  to alac (default) or aac based formats. logging is controlled by `--report-path`
# . means current directory
audiotown convert . --report-path=.
audiotown convert . --codec=alac --report-path=. --dry-run
audiotown convert . --codec=aac --bitrate=256k --report-path=. --dry-run


# 5. video upgrade. source formats: AVI, RMVB
audiotown convert '/my/path/to/video_folder/' --to-video=mp4 --report-path
```

## Advanced Options

1. overview

  |Option|	Description|	Default|
  |:---|:---|---:|
  |`--codec`|	alac or aac. used with `convert`. |alac|
  |`--bitrate`|	Bitrate for AAC (128k, 256k, 320k). only useful when `--codec=aac`|	256k|
  |`--dry-run`|	Preview conversion without writing files. used with `convert`	|disabled|
  |`--find-duplicate`| finds potential duplicate files by parallel comparisions via `arist`, `title` and `file_name`.|
|disabled|
  |`--report-path`|	generates a full log, including a json. work with both `convert` and `stats`.	|disabled|

2. Examples
   1. Run a preview to see what would be converted:

    ```zsh
    # preview the conversion that will be done to any flac files in `AlbumFolder`. 
    audiotown convert ./AlbumFolder --dry-run
    ```

   2. use `codec` and `--bitrate`. It means the desired codec used for the output. 
  
    ```zsh
    audiotown convert . --codec=alac 
    audiotown convert . --codec=aac --bitrate=256k 
    audiotown convert . --codec=aac --bitrate=128k 
    ```

   3. It does not make sense to specify `bitrate` for lossless `alac` so `bitrate` will be ignored.

    ```zsh
    cd /my/media/folder
    audiotown convert . --codec=alac --bitrate=128k 
    ```
   4. find duplicates. the command looks at the metadata like aritst, title, file size and file name. it tries to find a unique key to create duplicate groups/sets.

    ```zsh
    cd /my/media/folder
    audiotown stats . --find-duplicate
    ```
    5. video transcoding
      ```zsh
      ```
## 🤝 Contributing

`Audiotown` is a labor of love built to handle my own 100GB+ library. If you find a file that crashes the scan, or if you have an idea to make the Apple-conversion even smoother, I’d love your input!

### How to Help:
* **Report Bugs:** Open an [Issue](https://github.com/zjgcainiao/audiotown/issues) if a specific audio format causes a hiccup. Please include the output of your `meta.txt`!
* **Feature Requests:** Want a specific target bitrate or a new "Theme" for the progress bar? Let me know in the Issues.
* **Code:** Pull Requests are welcome! 
    1. Fork the repo.
    2. Create a feature branch (`git checkout -b feature/AmazingFeature`).
    3. Commit your changes.
    4. Push to the branch and open a PR.

# LICENSE
Licensed under the [MIT License](https://raw.githubusercontent.com/zjgcainiao/audiotown/main/LICENSE).
