audio-classifier-tool 1.2.0__tar.gz

audio_classifier_tool-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: astral-sh/setup-uv@v5
+
+    - name: Install
+      run: uv sync
+
+    - name: Unit tests
+      run: uv run pytest
+
+    - name: Build and test the installed package
+      run: uv run pytest -m integration tests/integration/test_package_install.py
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: docker/setup-buildx-action@v3
+
+    - name: Build Docker image
+      uses: docker/build-push-action@v6
+      with:
+        context: .
+        push: false
+        tags: audioclassifier:ci
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

audio_classifier_tool-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: astral-sh/setup-uv@v5
+
+    - name: Install
+      run: uv sync
+
+    - name: Unit tests
+      run: uv run pytest
+
+    - name: Build
+      run: uv build
+
+    - name: Publish
+      run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

audio_classifier_tool-1.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+dist/
+
+# App working dirs
+downloads/
+output/
+local_models/
+
+# Data artifacts
+*.mp3
+*.wav
+*.log
+*.db
+*.out
+*.json
+*.txt
+
+# macOS
+.DS_Store

audio_classifier_tool-1.2.0/.python-version

@@ -0,0 +1 @@
+3.13

audio_classifier_tool-1.2.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# AudioClassifier
+
+Detects and cuts target segments (ads by default) from audio. Installable package (`audioclassifier`) usable as a library (`audioclassifier.process_audio`) or CLI.
+
+## Commands
+
+- `uv sync` — install deps + the package (uv only, no pip/requirements.txt)
+- `PAYLOAD='{"source": ..., "name": ..., "audio_url": ...}' uv run audioclassifier --detection examples/configs/ads.toon` — process one audio file (needs `OPENAI_API_KEY`, `ffmpeg`)
+- `uv run pytest` — unit tests; `-m integration` for the full-pipeline run (see tests/README.md)
+- CLI logs go to `audioclassifier.log`, not the console; library imports are side-effect free (NullHandler logger)
+
+## Architecture (src/audioclassifier/)
+
+- `__init__.py` — public API: `process_audio(...)`, `train_text_classifier()`
+- `cli.py` — CLI entry point; `--detection <name|path>` selects a detection config
+- `processing/` — download, transcribe (faster-whisper), cut (soundfile/numpy)
+- `detection/` — LLM verification via pydantic-ai (`LLM_MODEL`, any provider), self-distilled text classifier
+- `config/` — constants, detection config loader
+- `cloud/` — all cloud integrations live here, nothing cloud-touching outside it (today: optional S3 upload of outputs via `storage=`)
+- No bundled classifier: users supply a `.toon` config (names resolve from `./configs/`) or pass instructions/keywords directly; examples in `examples/configs/`
+- `tests/unit/` mirrors this layout (`tests/unit/cloud/test_storage.py` ↔ `cloud/storage.py`)
+
+## Code Style
+
+- Comments only when necessary, and concise — no narrating what the code already says
+- Simple implementations over clever ones; no complexity for its own sake
+- Standard Python conventions; `_`-prefix for module-internal functions and state
+- Segregate by concern into packages — cloud code under `cloud/`, detection under `detection/`, audio work under `processing/`

audio_classifier_tool-1.2.0/Dockerfile

@@ -0,0 +1,36 @@
+FROM nvidia/cuda:12.0.0-base-ubuntu22.04
+
+# Set environment variables to prevent user interaction during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install FFmpeg and system libraries (Python itself is managed by uv)
+RUN apt-get update && \
+    apt-get install -y \
+    ffmpeg \
+    build-essential \
+    libavcodec-extra \
+    vim \
+    iputils-ping && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.8 /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Dependency layer: cached unless the lockfile or python version changes
+COPY pyproject.toml uv.lock .python-version /app/
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Pre-download Whisper model during build (before src so code changes don't invalidate it)
+RUN /app/.venv/bin/python -c "from faster_whisper import WhisperModel; import os; os.makedirs('/app/local_models/tiny', exist_ok=True); WhisperModel('tiny', download_root='/app/local_models/tiny')"
+
+COPY src/ /app/src
+COPY examples/configs/ /app/configs
+RUN uv sync --frozen --no-dev
+
+
+# Let ctranslate2 find the pip-installed cuBLAS/cuDNN libraries
+ENV LD_LIBRARY_PATH=/app/.venv/lib/python3.13/site-packages/nvidia/cublas/lib:/app/.venv/lib/python3.13/site-packages/nvidia/cudnn/lib:$LD_LIBRARY_PATH
+
+CMD ["/app/.venv/bin/audioclassifier"]

audio_classifier_tool-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Jon Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

audio_classifier_tool-1.2.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: audio-classifier-tool
+Version: 1.2.0
+Summary: Detect and cut target segments (ads by default) from audio, config-driven and LLM-verified
+Project-URL: Homepage, https://github.com/jon-fox/audio-classifier-tool
+Project-URL: Repository, https://github.com/jon-fox/audio-classifier-tool
+Author: Jon Fox
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ad-removal,ads,audio,classifier,podcast,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.13
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: boto3>=1.40.21
+Requires-Dist: ctranslate2==4.8.2
+Requires-Dist: faster-whisper==1.2.1
+Requires-Dist: numpy>=2
+Requires-Dist: nvidia-cublas-cu12; sys_platform == 'linux'
+Requires-Dist: nvidia-cudnn-cu12==9.*; sys_platform == 'linux'
+Requires-Dist: openai>=2
+Requires-Dist: pydantic-ai-slim[openai]>=2
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: python-toon>=0.1.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: scikit-learn>=1.9.1
+Requires-Dist: soundfile>=0.14.0
+Description-Content-Type: text/markdown
+
+# AudioClassifier - Dynamic Classifier used for Audio Segment Identification and Removal
+
+Runs locally by default: one audio file in, filtered audio out. Needs an OpenAI API key and `ffmpeg`.
+
+## Quick Start
+
+```bash
+uv sync
+export OPENAI_API_KEY=<your-key>
+
+PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  uv run audioclassifier --detection examples/configs/ads.toon
+```
+
+Results land in `output/<source>/<name>/`: the original mp3, the cleaned `*_filtered.mp3`, and a `transcripts/` dir with what was transcribed and each LLM cut/keep decision (with reasoning). Or with Docker:
+
+```bash
+docker build -t audioclassifier-app .
+docker run --gpus all \
+  -e OPENAI_API_KEY=<your-key> \
+  -e DETECTION_CONFIG=ads \
+  -e PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  -v "$(pwd)/output:/app/output" \
+  audioclassifier-app
+```
+
+Drop `--gpus all` to run on CPU (slower). The same container runs on any GPU box — RunPod, Modal, a gaming PC.
+
+## As a Library
+
+```bash
+uv add audio-classifier-tool      # pip install audio-classifier-tool
+```
+
+```python
+import audioclassifier
+
+result = audioclassifier.process_audio(
+    source="My Show",
+    name="Episode 1",
+    audio_url="<mp3-url>",
+    detection="examples/configs/ads.toon",  # a .toon path or a name in ./configs
+    detection_instructions="...",           # or pass the prompt directly
+    detection_keywords=["use code", ...],   # and the keyword gate
+)
+print(result["output_path"], result["seconds_removed"])
+```
+
+Importing has no side effects; configure the `"audioclassifier"` logger to see progress.
+
+For a real end-to-end run with live console output and a decision summary:
+
+```bash
+uv run python examples/process_audio.py "<mp3-url>"
+```
+
+## How It Works
+
+- Downloads the audio from the `PAYLOAD` JSON (`source`, `name`, `audio_url`, optional `description`)
+- Transcribes with faster-whisper (GPU-accelerated, CPU works too)
+- Detects target segments with OpenAI — ads by default
+- Cuts them and re-assembles the audio
+
+## Detection
+
+The classifier is fully yours to define — nothing is bundled. A [TOON](https://github.com/toon-format/spec) config supplies the keywords and prompts: select one with `--detection <name|path>` or `DETECTION_CONFIG` (names resolve from `./configs/`), or pass the prompt and keywords directly (`detection_instructions`/`detection_keywords` in the API, `DETECTION_INSTRUCTIONS`/`DETECTION_KEYWORDS` env vars). Complete examples live in `examples/configs/` (ads, politics).
+
+## Text Classifier (optional, opt-in)
+
+A self-distilled local classifier can add a third detection signal alongside keywords and audio analysis. Every processed audio file writes LLM-labeled decisions under `output/**/transcripts/` — that corpus is the classifier's training data, and it grows with each run.
+
+Enable with `USE_TEXT_CLASSIFIER=true`: the classifier's flagged ranges join the LLM prompt (advisory only — the LLM still decides), and it retrains automatically after each run from the **full accumulated history** (retraining is from scratch, in seconds, so nothing is ever forgotten). Refresh manually anytime:
+
+```bash
+uv run python examples/train_classifier.py          # or audioclassifier.train_text_classifier()
+```
+
+How it propagates: the durable memory is the decision files in `output/` — the model file (`local_models/text_classifier.joblib`) is a disposable cache rebuilt from them. Editing a decision file's `cut_ranges_seconds` after listening feeds your correction into the next training pass. In Docker, mount `local_models/` alongside `output/` to carry the model between containers (the data already survives via the `output/` mount).
+
+## Parallelism
+
+One audio file per `process_audio` call. Multiple processes are safe, even in the same directory — downloads and segment audio live in per-run temp dirs, and the classifier model is written atomically. Within one process, run audio files sequentially (Whisper models load once and are reused); concurrent runs in threads are supported only with one shared detection config. Don't feed the same audio to two processes at once — they'd write the same output files.
+
+## Options
+
+- `LLM_MODEL` — any [pydantic-ai model string](https://ai.pydantic.dev/models/) (default `openai:gpt-5.6`; e.g. `openai:gpt-5-nano` for cheapest, `anthropic:claude-sonnet-4-6`, `ollama:qwen3` — non-OpenAI providers may need their extra installed)
+- `DISCORD_ALERTS=true DISCORD_WEBHOOK_URL=<url>` — processing alerts in Discord
+- `storage="s3://bucket/prefix"` (API) or `"storage"` in `PAYLOAD` — upload the run's outputs (audio + transcripts + decisions) to S3 under `<prefix>/<source>/<name>/`, using ambient AWS credentials
+
+## License
+
+[MIT](LICENSE)

audio_classifier_tool-1.2.0/README.md

@@ -0,0 +1,92 @@
+# AudioClassifier - Dynamic Classifier used for Audio Segment Identification and Removal
+
+Runs locally by default: one audio file in, filtered audio out. Needs an OpenAI API key and `ffmpeg`.
+
+## Quick Start
+
+```bash
+uv sync
+export OPENAI_API_KEY=<your-key>
+
+PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  uv run audioclassifier --detection examples/configs/ads.toon
+```
+
+Results land in `output/<source>/<name>/`: the original mp3, the cleaned `*_filtered.mp3`, and a `transcripts/` dir with what was transcribed and each LLM cut/keep decision (with reasoning). Or with Docker:
+
+```bash
+docker build -t audioclassifier-app .
+docker run --gpus all \
+  -e OPENAI_API_KEY=<your-key> \
+  -e DETECTION_CONFIG=ads \
+  -e PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  -v "$(pwd)/output:/app/output" \
+  audioclassifier-app
+```
+
+Drop `--gpus all` to run on CPU (slower). The same container runs on any GPU box — RunPod, Modal, a gaming PC.
+
+## As a Library
+
+```bash
+uv add audio-classifier-tool      # pip install audio-classifier-tool
+```
+
+```python
+import audioclassifier
+
+result = audioclassifier.process_audio(
+    source="My Show",
+    name="Episode 1",
+    audio_url="<mp3-url>",
+    detection="examples/configs/ads.toon",  # a .toon path or a name in ./configs
+    detection_instructions="...",           # or pass the prompt directly
+    detection_keywords=["use code", ...],   # and the keyword gate
+)
+print(result["output_path"], result["seconds_removed"])
+```
+
+Importing has no side effects; configure the `"audioclassifier"` logger to see progress.
+
+For a real end-to-end run with live console output and a decision summary:
+
+```bash
+uv run python examples/process_audio.py "<mp3-url>"
+```
+
+## How It Works
+
+- Downloads the audio from the `PAYLOAD` JSON (`source`, `name`, `audio_url`, optional `description`)
+- Transcribes with faster-whisper (GPU-accelerated, CPU works too)
+- Detects target segments with OpenAI — ads by default
+- Cuts them and re-assembles the audio
+
+## Detection
+
+The classifier is fully yours to define — nothing is bundled. A [TOON](https://github.com/toon-format/spec) config supplies the keywords and prompts: select one with `--detection <name|path>` or `DETECTION_CONFIG` (names resolve from `./configs/`), or pass the prompt and keywords directly (`detection_instructions`/`detection_keywords` in the API, `DETECTION_INSTRUCTIONS`/`DETECTION_KEYWORDS` env vars). Complete examples live in `examples/configs/` (ads, politics).
+
+## Text Classifier (optional, opt-in)
+
+A self-distilled local classifier can add a third detection signal alongside keywords and audio analysis. Every processed audio file writes LLM-labeled decisions under `output/**/transcripts/` — that corpus is the classifier's training data, and it grows with each run.
+
+Enable with `USE_TEXT_CLASSIFIER=true`: the classifier's flagged ranges join the LLM prompt (advisory only — the LLM still decides), and it retrains automatically after each run from the **full accumulated history** (retraining is from scratch, in seconds, so nothing is ever forgotten). Refresh manually anytime:
+
+```bash
+uv run python examples/train_classifier.py          # or audioclassifier.train_text_classifier()
+```
+
+How it propagates: the durable memory is the decision files in `output/` — the model file (`local_models/text_classifier.joblib`) is a disposable cache rebuilt from them. Editing a decision file's `cut_ranges_seconds` after listening feeds your correction into the next training pass. In Docker, mount `local_models/` alongside `output/` to carry the model between containers (the data already survives via the `output/` mount).
+
+## Parallelism
+
+One audio file per `process_audio` call. Multiple processes are safe, even in the same directory — downloads and segment audio live in per-run temp dirs, and the classifier model is written atomically. Within one process, run audio files sequentially (Whisper models load once and are reused); concurrent runs in threads are supported only with one shared detection config. Don't feed the same audio to two processes at once — they'd write the same output files.
+
+## Options
+
+- `LLM_MODEL` — any [pydantic-ai model string](https://ai.pydantic.dev/models/) (default `openai:gpt-5.6`; e.g. `openai:gpt-5-nano` for cheapest, `anthropic:claude-sonnet-4-6`, `ollama:qwen3` — non-OpenAI providers may need their extra installed)
+- `DISCORD_ALERTS=true DISCORD_WEBHOOK_URL=<url>` — processing alerts in Discord
+- `storage="s3://bucket/prefix"` (API) or `"storage"` in `PAYLOAD` — upload the run's outputs (audio + transcripts + decisions) to S3 under `<prefix>/<source>/<name>/`, using ambient AWS credentials
+
+## License
+
+[MIT](LICENSE)

audio_classifier_tool-1.2.0/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  audioclassifier:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - PAYLOAD=${PAYLOAD}
+      - DETECTION_CONFIG=${DETECTION_CONFIG:-ads}
+    volumes:
+      - ./output:/app/output

audio_classifier_tool-1.2.0/examples/configs/ads.toon

@@ -0,0 +1,6 @@
+name: ads
+keywords[207]: signing up,use the code,support the show,use code,this episode is brought to you by,this show is brought to you by,"support for \\w+ comes from","i've been using \\w+",supplies are limited,"and enter code \\w+ at checkout",brought to you,this episode is,sponsors,sponsor,click the link in the description to find out more,sponsored by,advertisement,"visit [\\w-]+\\.com to save",use the promo code,"visit [-\\w.]+ to learn more",sponsoring,limited time,download the app,paid for by,"get \\d+% off your","save \\d+% on your","\\d+% discount on your","get \\d+% off",take a moment to thank our sponsor,purchase,sale,checkout,special offer,discount,discount code,promo code,promo,code,deal,offer,subscription service that,exclusive offer,"limited[-\\s]?time deal","limited[-\\s]?time offer","limited[-\\s]?time discount","limited[-\\s]?time sale",partnering,partner,partnered,promotion,link in the episode description,highly recommend,you have to try,shop,shop now,exclusive deal,affiliate link,commission earned,as an affiliate,partner program,affiliate disclosure,brought to you in part by,our friends at,a quick word from our sponsors,"listener[-\\s]?supported",thanks to our sponsor,subscribe today,try it for free,sign up now,don't miss out,order now,learn more,click here,visit now,explore more,read more,get your first month free,free trial,no obligation,"money[-\\s]?back guarantee",best price,partnered with,in collaboration with,powered by,endorsed by,brought to you by our partners,"(visit|check\\s(out|us\\sat|our\\swebsite)|go\\sto)\\s[\\w-]+(\\.[a-z]{2,})",act now,offer valid until,use our code,check the link below,click to learn more,brought to you in partnership with,save big,big savings,limited stock,early bird offer,new customers only,join now,exclusive for listeners,refer a friend,referral bonus,sign up for exclusive perks,try it today,as seen on,number one choice,voted best by,receive your,guaranteed results,award winning,customer favorite,see why everyone loves,start your journey,get access now,unbeatable value,get started today,your exclusive chance,contact us for more,fast delivery,don't delay,best in class,industry leading,on sale now,your satisfaction guaranteed,bet now,place your bets,gamble responsibly,must be 18 or older,download the draftkings app,odds boost,promo odds,parlay insurance,nicotine pouches,vape pods,tobacco-free nicotine,switch to vaping,smokeless alternative,juul compatible,telehealth visit,online doctor,rx delivered,consult a licensed physician,clinically proven results,fda cleared,lab-tested,doctor-formulated,ashwagandha gummies,adaptogen blend,hormone balancing,bedroom confidence,boost libido,feminine care,testosterone support,sexual wellness,lasting longer,increase stamina,intimate oil,male enhancement,natural male enhancement,anti-aging serum,retinol cream,collagen peptides,hair thickening,hair-loss solution,dermatologist recommended,clean beauty,spf moisturizer,meal kit,fresh ingredients delivered,chef-curated recipes,coffee subscription,wine club,snack box,first box free,robo-advisor,cryptocurrency exchange,commission-free trading,investing app,refinance your loan,credit repair,cash-back card,vpn service,password manager,cloud backup,identity theft protection,malware scan,data breach monitoring,secure browser,coding bootcamp,online mba,certificate program,career coaching,learn to code,masterclass,course bundle,discount flights,hotel deals,vacation package,airport transfer,ride credit,e-bike subscription,donate today,matching gift,join the movement,support our mission,paid for by the committee,grassroots campaign
+prompts:
+  assistant_instructions: "Your role is to analyze text or files for advertisements. Prioritize accuracy and ensure all responses are concise and well-structured.\nWhen provided with specific scoring or timestamping instructions, follow them carefully."
+  sponsor_instructions: "Please review the following podcast\ndescription and extract only the names of sponsors, advertisers,\ncompanies, or organizations mentioned. Exclude any other details, links, or additional context.\nProvide just the names.\n\nExample Output:\nSponsors: [Company A, Company B]"
+  detection_instructions: "On a scale of 1-100, evaluate the confidence that the attached text contains an advertisement or institutional promotion.\n\n        ### Guidelines for Detection:\n\n        #### Handling Fragmented Content:\n        - Evaluate individual text segments. For segments that appear incomplete or ambiguous, include the preceding and following segments within a **10-20 second window** to ensure the full ad is captured.\n        - Prioritize removing content if:\n          - It contains explicit ad indicators, such as mentions of sponsors, products, or services.\n          - It includes calls to action, promotional language, or website/promo code references.\n        - It is acceptable to capture some non-adjacent content as long as it ensures the entire ad is removed.\n        - Avoid including unrelated segments that clearly lack ad indicators or disrupt the flow of detection.\n        - Use the larger window only for content likely to span multiple segments (e.g., longer ad reads or storytelling formats).\n\n        #### General Indicators:\n        - Mentions of organizations, sponsors, or products, explicitly or indirectly.\n        - Promotion of a service, product, subscription, or institution.\n        - Highlighting unique benefits, features, or incentives, such as cost savings or exclusivity.\n        - Encouraging listeners to trust or engage with a brand.\n        - Contextual framing: Introducing a problem or need before recommending a solution.\n\n        #### Institutional Promotions:\n        - Promotion of an organization's **reputation, values, or societal contributions** rather than a specific product or service.\n        - Examples include:\n          - A corporation highlighting its environmental efforts (e.g., \"BP is committed to sustainability and a greener future\").\n          - A university promoting its brand or academic excellence (e.g., \"Georgia Tech is a leader in innovation and research\").\n          - Government agencies, NGOs, or advocacy groups promoting awareness or community engagement (e.g., \"Support our mission to fight climate change\").\n        - Indicators of institutional promotions:\n          - Statements reinforcing credibility, leadership, or legacy (e.g., \"A trusted name for over 100 years\").\n          - Public relations-driven messaging emphasizing goodwill or societal impact.\n          - Invitations to explore the organization's work rather than purchase a product (e.g., \"Learn more about our mission\").\n\n        ##### Gambling and Betting:\n        - Mentions of betting platforms, casinos, or wagering apps.\n        - Use of odds, disclaimers, or age restrictions (e.g., \"Must be 21 or older\").\n        - Phrases like \"risk-free bets,\" \"lock in your picks,\" or \"bet responsibly.\"\n\n        ##### Tobacco, Nicotine, and Vaping:\n        - Mentions of e-cigarettes, vaping pods, nicotine pouches, or smokeless products.\n        - Framing products as harm reduction or \"cleaner alternatives.\"\n        - Phrases like \"quit smoking the smart way,\" \"nicotine without the smoke.\"\n\n        ##### Pharmaceuticals and Health Claims:\n        - Promotion of prescription or over-the-counter drugs, supplements, or treatments.\n        - Health claims (e.g., \"boost immunity,\" \"clinically proven,\" \"doctor recommended\").\n        - References to FDA approval or regulatory compliance.\n\n        ##### Adult Content and Intimate Wellness Products:\n        - Promotion of dating platforms, adult content, or intimacy-related services.\n        - **For men**:\n        - Phrases like \"natural male enhancement,\" \"improve performance,\" \"testosterone boosters.\"\n        - **For women**:\n        - Terms like \"intimate wellness,\" \"boost libido,\" \"feminine rejuvenation,\" \"feel sexier.\"\n        - Euphemistic or pseudo-medical language around intimacy, confidence, or bedroom health.\n        - Includes supplements, devices, oils, and therapies marketed for sexual benefit or appeal.\n\n        ##### Gender-Targeted Lifestyle and Beauty Promotions:\n        - Skincare, makeup, cosmetics, or beauty product promotions.\n        - Phrases like \"glowing skin,\" \"age-defying,\" \"get your best look.\"\n        - Hair care, waxing, nail, or personal grooming products.\n        - Phrases like \"salon-quality at home,\" \"confidence starts with your hair.\"\n        - Self-care and empowerment framing.\n        - \"You deserve it,\" \"treat yourself,\" \"upgrade your routine.\"\n        - Weight loss or body image-focused products (e.g., slimming teas, detox kits, body sculpting).\n        - \"Flatten your stomach,\" \"get your summer body,\" \"shed stubborn weight.\"\n\n        #### Common Podcast Ad Categories\n        Flag content that includes brand mentions, promo codes, or clear calls to action in these frequent podcast-ad verticals:\n        - **Finance & Investing** - credit cards, trading apps, robo-advisors (\"get $10 in free BTC\").\n        - **Tech & Cybersecurity** - VPNs, password managers, cloud backup (\"try it free for 30 days\").\n        - **Food & Beverage Delivery** - meal kits, snack boxes, coffee/wine clubs (\"use code PODCAST\").\n        - **Health & Wellness Services** - telehealth, therapy platforms, fitness apps, at-home lab tests.\n        - **DTC Home & Lifestyle** - mattresses, bedding, furniture-in-a-box, home security.\n        - **Beauty & Grooming** - razor clubs, hair-loss treatments, skincare subscriptions.\n        - **Education & Career** - online courses, coding bootcamps, certificate programs.\n        - **Pet Products** - pet-food subscriptions, tele-vet services, training apps.\n        - **Entertainment & Media** - audiobooks, streaming services, ticket platforms.\n        - **Travel & Mobility** - airlines, vacation bundles, rental cars, micro-mobility.\n        - **Charitable & Political Appeals** - nonprofit fundraising, ballot-initiative promotions.\n\n        Look for discount language, free trials, urgency (\"sign up today\"), or problem-solution framing to confirm promotional intent.\n\n        #### Calls to Action:\n        - Language prompting actions like:\n          - Visiting a website or using a promo code (e.g., \"Use code PODCAST for 20% off\").\n          - Signing up, downloading, subscribing, or purchasing.\n          - Exploring or engaging with a mission, values, or achievements (e.g., \"Explore our impact.\").\n\n        #### Distinctive Features:\n        - Polished delivery styles (e.g., rehearsed tone, slogans, or taglines).\n        - Emphasis on specific benefits or features.\n        - Changes in tone, speed, or phrasing signaling promotional content.\n        - Problem-solution narratives leading to product recommendations.\n\n        #### Common Promotional Elements:\n        - Mentions of discounts, limited-time offers, or urgency (e.g., \"Save now,\" \"Exclusive to listeners\").\n        - Encouragement to act immediately (e.g., \"Don't wait, act now\").\n        - References to solving a problem or enhancing a listener's experience.\n\n        {optional_sponsors_section}\n\n        ### Scoring and Timestamping:\n        - Assign confidence scores as follows:\n          - Above 60: Strong ad indicators (e.g., sponsor mentions, calls to action, promo codes).\n          - 40-60: Content in the 40-60 range may include partial ad-like phrases but lacks a clear call to action or sponsorship mention.\n          - Below 40: No clear ad indicators.\n        - Ads often run for 30-60 seconds, but timestamps should match detected promotional content rather than assume a set length.\n        - If multiple ad or promotional segments are detected, provide timestamps for each segment individually. However, if an ad is fragmented across a longer conversational segment, merge timestamps where necessary to capture the full promotional message without splitting it unnaturally.\n        - For conversational-style ads that blend with organic content, focus on identifying the entire promotional context rather than isolating individual phrases. Ensure that subtle sponsorship mentions or integrated endorsements are fully captured.\n\n        Output:\n        Be concise, providing only the confidence score and the timestamps for each detected ad or promotional segment.\n\n        Return only a valid JSON object with no additional text, explanations, or formatting. The response must strictly follow this format:\n        {\n          \"confidence_score\": 85,\n          \"timestamps\": [\n            {\"start\": 0.00, \"end\": 30.00},\n            {\"start\": 45.00, \"end\": 75.00},\n            {\"start\": 120.00, \"end\": 150.00}\n          ]\n        }"

audio_classifier_tool-1.2.0/examples/configs/politics.toon

@@ -0,0 +1,5 @@
+name: politics
+keywords[10]: election,senator,congress,campaign,ballot,legislation,president,governor,policy debate,partisan
+prompts:
+  assistant_instructions: Your role is to analyze podcast transcripts for political content. Prioritize accuracy and follow the scoring and timestamping instructions carefully.
+  detection_instructions: "On a scale of 1-100, evaluate the confidence that the attached transcript contains political discussion (campaigns, elections, legislation, partisan commentary).\n\n{optional_sponsors_section}\n\nReport each distinct political segment as its own timestamp range; never span unrelated content between two segments. Return the confidence score and the timestamps for each detected segment."

audio_classifier_tool-1.2.0/examples/process_audio.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+"""Run the real pipeline against an audio URL using the library API.
+
+    export OPENAI_API_KEY=<your-key>
+    uv run python examples/process_audio.py "<mp3-url>" \
+        --source "My Show" --name "Episode 1"
+
+The classifier is config-driven: --detection selects what gets found and cut.
+This example defaults to the ad classifier at examples/configs/ads.toon;
+examples/configs/politics.toon shows a different classifier — pass it with:
+
+    --detection examples/configs/politics.toon
+
+Progress streams to the console; results and per-segment LLM decisions are
+printed at the end.
+"""
+
+import argparse
+import glob
+import json
+import logging
+import os
+
+import audioclassifier
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("audio_url", help="audio file url")
+    parser.add_argument("--source", default="Example Source")
+    parser.add_argument("--name", default="Example Audio")
+    parser.add_argument(
+        "--detection",
+        default=os.path.join(os.path.dirname(__file__), "configs", "ads.toon"),
+        help="detection config .toon path or a name in ./configs "
+        "(default: the example ad classifier)",
+    )
+    args = parser.parse_args()
+
+    logger = logging.getLogger("audioclassifier")
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+    print(f"Detection config: {args.detection}")
+    result = audioclassifier.process_audio(
+        source=args.source,
+        name=args.name,
+        audio_url=args.audio_url,
+        detection=args.detection,
+    )
+
+    print("\n=== Result ===")
+    print(f"Output:            {result['output_path']}")
+    print(f"Original duration: {result['original_duration']:.0f}s")
+    print(f"Filtered duration: {result['filtered_duration']:.0f}s")
+    print(f"Removed:           {result['seconds_removed']:.0f}s")
+
+    transcripts_dir = os.path.join(
+        os.path.dirname(result["output_path"]), "transcripts"
+    )
+    for path in sorted(glob.glob(os.path.join(transcripts_dir, "*_decision.json"))):
+        decision = json.load(open(path))
+        print(f"\n{os.path.basename(path)}: {decision['action'].upper()}")
+        if decision["cut_ranges_seconds"]:
+            print(f"  ranges: {decision['cut_ranges_seconds']}")
+        print(f"  reasoning: {decision['reasoning']}")
+
+
+if __name__ == "__main__":
+    main()

audio_classifier_tool-1.2.0/examples/train_classifier.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+"""Train the self-distilled ad classifier from past runs' decision files.
+
+    uv run python examples/train_classifier.py [output-dir]
+
+Every processed audio file adds training data (transcripts labeled by the LLM's
+cut/keep decisions under output/). Once trained, runs automatically feed the
+classifier's flags to the LLM as an extra detection signal.
+"""
+
+import sys
+
+import audioclassifier
+
+
+def main():
+    output_dir = sys.argv[1] if len(sys.argv) > 1 else None
+    metrics = audioclassifier.train_text_classifier(output_dir)
+    print("Trained:")
+    for key, value in metrics.items():
+        print(f"  {key}: {value}")
+
+
+if __name__ == "__main__":
+    main()

audio_classifier_tool-1.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "audio-classifier-tool"
+version = "1.2.0"
+description = "Detect and cut target segments (ads by default) from audio, config-driven and LLM-verified"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [{ name = "Jon Fox" }]
+keywords = ["audio", "podcast", "ads", "ad-removal", "whisper", "classifier"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+    "backoff>=2.2.1",
+    "boto3>=1.40.21",
+    "ctranslate2==4.8.2",
+    "faster-whisper==1.2.1",
+    "numpy>=2",
+    # cuBLAS + cuDNN 9 for ctranslate2 GPU inference (previously bundled via torch/apt)
+    "nvidia-cublas-cu12; sys_platform == 'linux'",
+    "nvidia-cudnn-cu12==9.*; sys_platform == 'linux'",
+    "openai>=2",
+    "pydantic>=2.11.7",
+    "pydantic-ai-slim[openai]>=2",
+    "python-toon>=0.1.3",
+    "requests>=2.32.5",
+    "scikit-learn>=1.9.1",
+    "soundfile>=0.14.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jon-fox/audio-classifier-tool"
+Repository = "https://github.com/jon-fox/audio-classifier-tool"
+
+[project.scripts]
+audioclassifier = "audioclassifier.cli:main"
+
+[tool.pytest.ini_options]
+markers = ["integration: full pipeline run; needs OPENAI_API_KEY and network"]
+addopts = "-m 'not integration'"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/audioclassifier"]
+
+[dependency-groups]
+dev = [
+    "black>=26.5.1",
+    "pytest>=9.1.1",
+]

audio_classifier_tool-1.2.0/src/audioclassifier/__init__.py

@@ -0,0 +1,59 @@
+"""AudioClassifier: detect and cut target segments from audio (ads by default)."""
+
+
+def process_audio(
+    source,
+    name,
+    audio_url,
+    detection=None,
+    detection_instructions=None,
+    detection_keywords=None,
+    description=None,
+    storage=None,
+):
+    """Process one audio file: download, transcribe, detect, and cut.
+
+    source groups outputs (output/<source>/<name>/); name is used for the
+    output filenames. detection: a config name (in ./configs) or a .toon path;
+    detection_instructions / detection_keywords override the selected config
+    directly. description is optional context about the audio for the
+    detection config's context-extraction prompt. storage: optional
+    s3://bucket/prefix — outputs are uploaded under <prefix>/<source>/<name>/.
+    Returns a dict with output_path, filtered_duration, original_duration,
+    seconds_removed, and (with storage) the uploaded S3 URIs.
+
+    Configure the "audioclassifier" logger to see progress; set OPENAI_API_KEY
+    (or the provider key matching LLM_MODEL) before calling.
+    """
+    if detection or detection_instructions or detection_keywords:
+        from audioclassifier.config.detection_config import set_detection_config
+
+        set_detection_config(
+            detection,
+            instructions=detection_instructions,
+            keywords=detection_keywords,
+        )
+
+    from audioclassifier.cli import process_payload
+
+    return process_payload(
+        {
+            "source": source,
+            "name": name,
+            "audio_url": audio_url,
+            "description": description,
+            "storage": storage,
+        }
+    )
+
+
+def train_text_classifier(output_dir=None):
+    """Train the self-distilled ad classifier from past runs' decision files.
+
+    Returns training metrics. The trained model is picked up automatically by
+    subsequent runs as an extra detection signal.
+    """
+    from audioclassifier.config.constants import FINISHED_MP3_DIR
+    from audioclassifier.detection import text_classifier
+
+    return text_classifier.train(output_dir or FINISHED_MP3_DIR)