whispero 0.1.0__tar.gz

whispero-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Neguiolidas
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

whispero-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: whispero
+Version: 0.1.0
+Summary: Universal audio transcription and deep analysis - Gemini native audio plus any OpenAI-compatible API
+Author: Neguiolidas
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Neguiolidas/whispero
+Project-URL: Repository, https://github.com/Neguiolidas/whispero
+Project-URL: Issues, https://github.com/Neguiolidas/whispero/issues
+Keywords: audio,transcription,whisper,speech-to-text,ai-agents,gemini
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Whispero
+
+Audio transcription and deep audio analysis with any OpenAI-compatible
+provider. Defaults to Gemini's native audio input (transcribes *and*
+reasons in one pass); also works with OpenAI, Groq, Together, or any
+Whisper-style `/v1/audio/transcriptions` endpoint.
+
+Unlike pure ASR models, the Gemini path processes audio with reasoning: it
+transcribes, cleans up, structures output, detects speakers, emotions, and
+action items in a single pass.
+
+## Install
+
+```bash
+pip install whispero
+```
+
+## Setup
+
+```bash
+# Gemini (default) - free key at https://aistudio.google.com/apikey
+export GEMINI_API_KEY="your-key-here"
+
+# ...or any provider key, picked up automatically
+export WHISPERO_API_KEY="your-key-here"
+export OPENAI_API_KEY="your-key-here"
+```
+
+## Usage
+
+```bash
+# Simple transcription, Gemini (Portuguese default)
+whispero meeting.mp3
+
+# English transcription
+whispero call.mp3 --lang en
+
+# YouTube URL directly, no download needed (Gemini only)
+whispero "https://www.youtube.com/watch?v=..." --lang en
+whispero-analyze "https://www.youtube.com/watch?v=..."
+
+# OpenAI-compatible provider (Whisper-style API)
+whispero meeting.mp3 --provider openai
+whispero meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1 \
+    --model whisper-large-v3
+
+# Deep analysis: transcript, speakers, tone, emotions, urgency,
+# intent, action items, key moments, irony/sarcasm detection
+whispero-analyze meeting.mp3
+whispero-analyze meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1
+
+# Faster upload for large files (compresses to opus 32k first, local files only)
+whispero long.mp3 --compress
+
+# Configurable fallback models (comma-separated, tried in order)
+whispero meeting.mp3 --fallback-models gemini-2.0-flash
+```
+
+## Features
+
+- Two providers: `gemini` (default, native audio + YouTube URLs) and `openai`
+  (any OpenAI-compatible `/v1/audio/transcriptions` endpoint)
+- Speaker diarization ([FALANTE 1], [FALANTE 2] with voice characteristics)
+- Retry with exponential backoff on rate limits and server errors
+- `--fallback-models`: configurable comma-separated fallback list
+- `--compress` flag: converts to opus 32k mono 16kHz via ffmpeg before upload
+- JSON validation on analysis output
+- Zero pip dependencies, only stdlib + ffmpeg
+
+## Benchmark
+
+50 seconds of real audio, Gemini (Portuguese):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~4s | faithful transcript |
+| transcribe.py --compress | ~4s | same, half the upload size |
+| audio_analyze.py | ~14s | full JSON analysis |
+
+GTA 6 trailer via YouTube URL (no download):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~12s | dialogue + song lyrics + on-screen text |
+| audio_analyze.py | ~23s | 4 speakers, tone, 9 key moments, intent |
+
+## License
+
+Apache 2.0 — see LICENSE.

whispero-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Whispero
+
+Audio transcription and deep audio analysis with any OpenAI-compatible
+provider. Defaults to Gemini's native audio input (transcribes *and*
+reasons in one pass); also works with OpenAI, Groq, Together, or any
+Whisper-style `/v1/audio/transcriptions` endpoint.
+
+Unlike pure ASR models, the Gemini path processes audio with reasoning: it
+transcribes, cleans up, structures output, detects speakers, emotions, and
+action items in a single pass.
+
+## Install
+
+```bash
+pip install whispero
+```
+
+## Setup
+
+```bash
+# Gemini (default) - free key at https://aistudio.google.com/apikey
+export GEMINI_API_KEY="your-key-here"
+
+# ...or any provider key, picked up automatically
+export WHISPERO_API_KEY="your-key-here"
+export OPENAI_API_KEY="your-key-here"
+```
+
+## Usage
+
+```bash
+# Simple transcription, Gemini (Portuguese default)
+whispero meeting.mp3
+
+# English transcription
+whispero call.mp3 --lang en
+
+# YouTube URL directly, no download needed (Gemini only)
+whispero "https://www.youtube.com/watch?v=..." --lang en
+whispero-analyze "https://www.youtube.com/watch?v=..."
+
+# OpenAI-compatible provider (Whisper-style API)
+whispero meeting.mp3 --provider openai
+whispero meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1 \
+    --model whisper-large-v3
+
+# Deep analysis: transcript, speakers, tone, emotions, urgency,
+# intent, action items, key moments, irony/sarcasm detection
+whispero-analyze meeting.mp3
+whispero-analyze meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1
+
+# Faster upload for large files (compresses to opus 32k first, local files only)
+whispero long.mp3 --compress
+
+# Configurable fallback models (comma-separated, tried in order)
+whispero meeting.mp3 --fallback-models gemini-2.0-flash
+```
+
+## Features
+
+- Two providers: `gemini` (default, native audio + YouTube URLs) and `openai`
+  (any OpenAI-compatible `/v1/audio/transcriptions` endpoint)
+- Speaker diarization ([FALANTE 1], [FALANTE 2] with voice characteristics)
+- Retry with exponential backoff on rate limits and server errors
+- `--fallback-models`: configurable comma-separated fallback list
+- `--compress` flag: converts to opus 32k mono 16kHz via ffmpeg before upload
+- JSON validation on analysis output
+- Zero pip dependencies, only stdlib + ffmpeg
+
+## Benchmark
+
+50 seconds of real audio, Gemini (Portuguese):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~4s | faithful transcript |
+| transcribe.py --compress | ~4s | same, half the upload size |
+| audio_analyze.py | ~14s | full JSON analysis |
+
+GTA 6 trailer via YouTube URL (no download):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~12s | dialogue + song lyrics + on-screen text |
+| audio_analyze.py | ~23s | 4 speakers, tone, 9 key moments, intent |
+
+## License
+
+Apache 2.0 — see LICENSE.

whispero-0.1.0/audio_analyze.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Whispero - deep audio analysis with any OpenAI-compatible provider.
+
+Usage:
+    audio_analyze.py <audio_file_or_url> [--provider gemini]
+    [--model gemini-2.5-flash] [--base-url URL] [--api-key KEY]
+    [--fallback-models m1,m2] [--compress]
+
+Providers:
+    gemini  - Google AI Studio, native audio input, YouTube URLs supported
+              (default, key via GEMINI_API_KEY or --api-key)
+    openai  - Any OpenAI-compatible API: transcribes via
+              /v1/audio/transcriptions then analyzes the text via
+              /v1/chat/completions (key via OPENAI_API_KEY or --api-key,
+              URL via --base-url)
+
+Prints JSON with: transcript, speakers, tone, emotions, emotional_arc,
+urgency, intent, action_items, speaker_notes, key_moments,
+irony_detected, sarcasm_detected.
+
+Zero pip dependencies (stdlib + ffmpeg).
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import mimetypes
+import os
+import subprocess  # nosec B404
+import sys
+import tempfile
+import time
+import urllib.request
+import urllib.error
+
+DEFAULT_PROVIDER = "gemini"
+DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"
+DEFAULT_OPENAI_MODEL = "whisper-1"
+DEFAULT_CHAT_MODEL = "gpt-4o-mini"
+GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
+OPENAI_API_BASE = "https://api.openai.com/v1"
+MAX_RETRIES = 3
+RETRY_DELAYS = [2, 5, 10]
+
+ANALYZE_PROMPT = (
+    "Analise este áudio em profundidade e retorne um JSON com os seguintes campos:\n"
+    "- transcript: transcrição fiel em português, com marcação de falante se houver mais de um ([FALANTE 1], [FALANTE 2])\n"
+    "- speakers: lista de falantes detectados com características de voz de cada um\n"
+    "- tone: tom geral (ex: calmo, tenso, animado, irritado, sarcástico)\n"
+    "- emotions: lista das emoções detectadas com intensidade (0-1)\n"
+    "- emotional_arc: como as emoções mudam ao longo do áudio (início/meio/fim)\n"
+    "- urgency: nível de urgência 0-10 e justificativa curta\n"
+    "- intent: o que o falante quer (pedido, desabafo, informação, decisão, etc.)\n"
+    "- action_items: lista de ações ou compromissos mencionados\n"
+    "- speaker_notes: características de voz (ritmo, pausas, ênfases, sotaque)\n"
+    "- key_moments: lista de momentos importantes com timestamp aproximado e descrição\n"
+    "- irony_detected: true/false com explicação se houver\n"
+    "- sarcasm_detected: true/false com explicação se houver\n"
+    "Retorne APENAS o JSON, sem markdown nem comentários."
+)
+
+ANALYZE_TEXT_PROMPT = (
+    "Analise a transcrição abaixo em profundidade e retorne um JSON com os "
+    "seguintes campos:\n"
+    "- transcript: a transcrição recebida, com marcação de falante se houver "
+    "mais de um ([FALANTE 1], [FALANTE 2])\n"
+    "- speakers: lista de falantes detectados (se identificável pelo texto)\n"
+    "- tone: tom geral (ex: calmo, tenso, animado, irritado, sarcástico)\n"
+    "- emotions: lista das emoções detectadas com intensidade (0-1)\n"
+    "- emotional_arc: como as emoções mudam ao longo do texto (início/meio/fim)\n"
+    "- urgency: nível de urgência 0-10 e justificativa curta\n"
+    "- intent: o que o falante quer (pedido, desabafo, informação, decisão, etc.)\n"
+    "- action_items: lista de ações ou compromissos mencionados\n"
+    "- key_moments: lista de momentos importantes com descrição\n"
+    "- irony_detected: true/false com explicação se houver\n"
+    "- sarcasm_detected: true/false com explicação se houver\n"
+    "Retorne APENAS o JSON, sem markdown nem comentários.\n\nTranscrição:\n"
+)
+
+
+def is_url(s: str) -> bool:
+    return s.startswith("http://") or s.startswith("https://")
+
+
+def get_api_key(args) -> str:
+    for src in (args.api_key, os.environ.get("WHISPERO_API_KEY"),
+                os.environ.get("GEMINI_API_KEY"),
+                os.environ.get("OPENAI_API_KEY")):
+        if src and src.strip():
+            return src.strip()
+    print(
+        "error: no API key. Use --api-key or set WHISPERO_API_KEY "
+        "(or GEMINI_API_KEY / OPENAI_API_KEY).",
+        file=sys.stderr,
+    )
+    sys.exit(3)
+
+
+def compress_audio(src: str) -> str:
+    tmp = tempfile.NamedTemporaryFile(suffix=".ogg", delete=False)
+    tmp.close()
+    try:
+        subprocess.run(  # nosec B607 B603
+            ["ffmpeg", "-y", "-v", "error", "-i", src,
+             "-c:a", "libopus", "-b:a", "32k", "-ar", "16000", "-ac", "1",
+             tmp.name],
+            check=True, timeout=120,
+        )
+        return tmp.name
+    except (subprocess.CalledProcessError, FileNotFoundError,
+            subprocess.TimeoutExpired):
+        os.unlink(tmp.name)
+        return src
+
+
+def http_post_json(url: str, headers: dict, payload: dict,
+                   timeout: int = 180) -> dict | None:
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode("utf-8"),
+        headers=headers, method="POST",
+    )
+    last_err = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                return json.load(resp)
+        except urllib.error.HTTPError as e:
+            if e.code in (429, 500, 502, 503):
+                last_err = e
+            else:
+                body = e.read().decode(errors="replace")[:300]
+                print(f"error: API {e.code}: {body}", file=sys.stderr)
+                return None
+        except Exception as e:
+            last_err = e
+        if attempt < MAX_RETRIES - 1:
+            time.sleep(RETRY_DELAYS[attempt])
+    print(f"warn: failed after {MAX_RETRIES} tries: {last_err}", file=sys.stderr)
+    return None
+
+
+def extract_json(data: dict) -> dict | None:
+    try:
+        text = data["candidates"][0]["content"]["parts"][0]["text"].strip()
+    except (KeyError, IndexError, TypeError):
+        try:
+            text = data["choices"][0]["message"]["content"].strip()
+        except (KeyError, IndexError, TypeError):
+            return None
+    if text.startswith("```"):
+        text = text.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+# ---------------- Gemini provider ----------------
+
+def gemini_analyze(base: str, key: str, model: str,
+                   media_part: dict) -> dict | None:
+    url = f"{base}/{model}:generateContent?key={key}"
+    payload = {
+        "contents": [{"parts": [{"text": ANALYZE_PROMPT}, media_part]}],
+        "generationConfig": {"temperature": 0.2},
+    }
+    data = http_post_json(url, {"Content-Type": "application/json"}, payload)
+    return extract_json(data) if data else None
+
+
+# ---------------- OpenAI-compatible provider ----------------
+
+def openai_transcribe(base: str, key: str, model: str,
+                      audio_path: str) -> str | None:
+    import uuid
+    boundary = uuid.uuid4().hex
+    url = f"{base.rstrip('/')}/audio/transcriptions"
+    with open(audio_path, "rb") as fh:
+        audio_bytes = fh.read()
+    filename = os.path.basename(audio_path)
+    mime, _ = mimetypes.guess_type(audio_path)
+    mime = mime or "application/octet-stream"
+    parts = []
+    for name, value in (("model", model), ("response_format", "text")):
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"'
+            f'\r\n\r\n{value}\r\n'.encode()
+        )
+    parts.append(
+        f'--{boundary}\r\nContent-Disposition: form-data; name="file"; '
+        f'filename="{filename}"\r\nContent-Type: {mime}\r\n\r\n'.encode()
+        + audio_bytes + b'\r\n'
+    )
+    parts.append(f'--{boundary}--\r\n'.encode())
+    req = urllib.request.Request(
+        url, data=b"".join(parts),
+        headers={"Authorization": f"Bearer {key}",
+                 "Content-Type": f"multipart/form-data; boundary={boundary}"},
+        method="POST",
+    )
+    last_err = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            with urllib.request.urlopen(req, timeout=300) as resp:  # nosec B310
+                return resp.read().decode().strip() or None
+        except urllib.error.HTTPError as e:
+            if e.code in (429, 500, 502, 503):
+                last_err = e
+            else:
+                print(f"error: API {e.code}: {e.read().decode()[:300]}",
+                      file=sys.stderr)
+                return None
+        except Exception as e:
+            last_err = e
+        if attempt < MAX_RETRIES - 1:
+            time.sleep(RETRY_DELAYS[attempt])
+    print(f"warn: failed after {MAX_RETRIES} tries: {last_err}", file=sys.stderr)
+    return None
+
+
+def openai_analyze_text(base: str, key: str, model: str,
+                        transcript: str) -> dict | None:
+    url = f"{base.rstrip('/')}/chat/completions"
+    payload = {
+        "model": model,
+        "messages": [{"role": "user",
+                      "content": ANALYZE_TEXT_PROMPT + transcript}],
+        "temperature": 0.2,
+    }
+    data = http_post_json(
+        url, {"Content-Type": "application/json",
+              "Authorization": f"Bearer {key}"},
+        payload,
+    )
+    return extract_json(data) if data else None
+
+
+# ---------------- main ----------------
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Whispero deep audio analysis.")
+    p.add_argument("source", help="Audio file path or YouTube URL (gemini only)")
+    p.add_argument("--provider", default=DEFAULT_PROVIDER,
+                   choices=["gemini", "openai"])
+    p.add_argument("--model", default=None,
+                   help="Transcription model (default: gemini-2.5-flash / whisper-1)")
+    p.add_argument("--chat-model", default=DEFAULT_CHAT_MODEL,
+                   help="Chat model for text analysis step (openai provider)")
+    p.add_argument("--base-url", default=None,
+                   help="Custom API base URL for OpenAI-compatible providers")
+    p.add_argument("--api-key", default=None, help="API key (or env var)")
+    p.add_argument("--fallback-models", default="",
+                   help="Comma-separated fallback models to try in order")
+    p.add_argument("--compress", action="store_true",
+                   help="Compress to opus 32k before upload (local files only)")
+    args = p.parse_args()
+
+    key = get_api_key(args)
+    fallbacks = [m.strip() for m in args.fallback_models.split(",") if m.strip()]
+
+    if args.provider == "gemini":
+        model = args.model or DEFAULT_GEMINI_MODEL
+        models = [model] + [m for m in fallbacks if m != model]
+        base = GEMINI_API_BASE
+        tmp_path = None
+        if is_url(args.source):
+            media_part = {"file_data": {"file_uri": args.source}}
+        else:
+            if not os.path.isfile(args.source):
+                print(f"error: file not found: {args.source}", file=sys.stderr)
+                return 2
+            src = args.source
+            if args.compress:
+                tmp_path = compress_audio(src)
+                if tmp_path != src:
+                    src = tmp_path
+            try:
+                mime, _ = mimetypes.guess_type(src)
+                mime = mime or "audio/ogg"
+                with open(src, "rb") as fh:
+                    b64 = base64.b64encode(fh.read()).decode("ascii")
+                media_part = {"inline_data": {"mime_type": mime, "data": b64}}
+            finally:
+                if tmp_path and tmp_path != args.source:
+                    os.unlink(tmp_path)
+        for m in models:
+            result = gemini_analyze(base, key, m, media_part)
+            if result:
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+                return 0
+            print(f"warn: no usable result from {m}, trying next...",
+                  file=sys.stderr)
+    else:  # openai-compatible: transcribe then analyze text
+        if is_url(args.source):
+            print("error: URL input only supported with --provider gemini",
+                  file=sys.stderr)
+            return 2
+        if not os.path.isfile(args.source):
+            print(f"error: file not found: {args.source}", file=sys.stderr)
+            return 2
+        model = args.model or DEFAULT_OPENAI_MODEL
+        models = [model] + [m for m in fallbacks if m != model]
+        base = args.base_url or OPENAI_API_BASE
+        src = args.source
+        tmp_path = None
+        if args.compress:
+            tmp_path = compress_audio(src)
+            if tmp_path != src:
+                src = tmp_path
+        try:
+            transcript = None
+            for m in models:
+                transcript = openai_transcribe(base, key, m, src)
+                if transcript:
+                    break
+                print(f"warn: transcription failed on {m}, trying next...",
+                      file=sys.stderr)
+            if not transcript:
+                print("error: transcription failed on all models",
+                      file=sys.stderr)
+                return 5
+            result = openai_analyze_text(base, key, args.chat_model, transcript)
+            if result:
+                result.setdefault("transcript", transcript)
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+                return 0
+        finally:
+            if tmp_path and tmp_path != args.source:
+                os.unlink(tmp_path)
+
+    print("error: no usable analysis from any model", file=sys.stderr)
+    return 5
+
+
+if __name__ == "__main__":
+    sys.exit(main())

whispero-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "whispero"
+version = "0.1.0"
+description = "Universal audio transcription and deep analysis - Gemini native audio plus any OpenAI-compatible API"
+readme = "README.md"
+authors = [{name = "Neguiolidas"}]
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+keywords = ["audio", "transcription", "whisper", "speech-to-text", "ai-agents", "gemini"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Neguiolidas/whispero"
+Repository = "https://github.com/Neguiolidas/whispero"
+Issues = "https://github.com/Neguiolidas/whispero/issues"
+
+[project.scripts]
+whispero = "transcribe:main"
+whispero-analyze = "audio_analyze:main"
+
+[tool.setuptools]
+py-modules = ["transcribe", "audio_analyze"]

whispero-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

whispero-0.1.0/transcribe.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Whispero - transcribe audio with any OpenAI-compatible provider.
+
+Usage:
+    transcribe.py <audio_file_or_url> [--provider gemini] [--lang pt]
+    [--model gemini-2.5-flash] [--base-url URL] [--api-key KEY]
+    [--fallback-models m1,m2] [--prompt "..."] [--compress]
+
+Providers:
+    gemini  - Google AI Studio, native audio input, YouTube URLs supported
+              (default, key via GEMINI_API_KEY or --api-key)
+    openai  - Any OpenAI-compatible API (OpenAI, Groq, Together, etc.)
+              uses /v1/audio/transcriptions (Whisper-style)
+              (key via OPENAI_API_KEY or --api-key, URL via --base-url)
+
+Prints the transcript to stdout. Zero pip dependencies (stdlib + ffmpeg).
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import mimetypes
+import os
+import subprocess  # nosec B404
+import sys
+import tempfile
+import time
+import urllib.request
+import urllib.error
+
+DEFAULT_PROVIDER = "gemini"
+DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"
+DEFAULT_OPENAI_MODEL = "whisper-1"
+GEMINI_API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
+OPENAI_API_BASE = "https://api.openai.com/v1"
+MAX_RETRIES = 3
+RETRY_DELAYS = [2, 5, 10]
+
+
+def is_url(s: str) -> bool:
+    return s.startswith("http://") or s.startswith("https://")
+
+
+def get_api_key(args) -> str:
+    for src in (args.api_key, os.environ.get("WHISPERO_API_KEY"),
+                os.environ.get("GEMINI_API_KEY"),
+                os.environ.get("OPENAI_API_KEY")):
+        if src and src.strip():
+            return src.strip()
+    print(
+        "error: no API key. Use --api-key or set WHISPERO_API_KEY "
+        "(or GEMINI_API_KEY / OPENAI_API_KEY).",
+        file=sys.stderr,
+    )
+    sys.exit(3)
+
+
+def compress_audio(src: str) -> str:
+    """Convert to low-bitrate opus for faster upload. Returns temp path."""
+    tmp = tempfile.NamedTemporaryFile(suffix=".ogg", delete=False)
+    tmp.close()
+    try:
+        subprocess.run(  # nosec B607 B603
+            ["ffmpeg", "-y", "-v", "error", "-i", src,
+             "-c:a", "libopus", "-b:a", "32k", "-ar", "16000", "-ac", "1",
+             tmp.name],
+            check=True, timeout=120,
+        )
+        return tmp.name
+    except (subprocess.CalledProcessError, FileNotFoundError,
+            subprocess.TimeoutExpired):
+        os.unlink(tmp.name)
+        return src
+
+
+def http_post(url: str, headers: dict, data: bytes | None = None,
+              timeout: int = 180) -> dict | None:
+    """POST with retry on 429/5xx. Returns parsed JSON or None."""
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    last_err = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                return json.load(resp)
+        except urllib.error.HTTPError as e:
+            if e.code in (429, 500, 502, 503):
+                last_err = e
+            else:
+                body = e.read().decode(errors="replace")[:300]
+                print(f"error: API {e.code}: {body}", file=sys.stderr)
+                return None
+        except Exception as e:
+            last_err = e
+        if attempt < MAX_RETRIES - 1:
+            time.sleep(RETRY_DELAYS[attempt])
+    print(f"warn: failed after {MAX_RETRIES} tries: {last_err}", file=sys.stderr)
+    return None
+
+
+# ---------------- Gemini provider ----------------
+
+def gemini_transcribe(base: str, key: str, model: str, prompt: str,
+                      media_part: dict) -> str | None:
+    url = f"{base}/{model}:generateContent?key={key}"
+    payload = {"contents": [{"parts": [{"text": prompt}, media_part]}]}
+    data = http_post(url, {"Content-Type": "application/json"},
+                     json.dumps(payload).encode())
+    if not data:
+        return None
+    try:
+        return data["candidates"][0]["content"]["parts"][0]["text"].strip()
+    except (KeyError, IndexError, TypeError):
+        return None
+
+
+# ---------------- OpenAI-compatible provider ----------------
+
+def openai_transcribe(base: str, key: str, model: str, audio_path: str,
+                      lang: str) -> str | None:
+    """Whisper-style /v1/audio/transcriptions with multipart upload."""
+    import uuid
+    boundary = uuid.uuid4().hex
+    url = f"{base.rstrip('/')}/audio/transcriptions"
+
+    with open(audio_path, "rb") as fh:
+        audio_bytes = fh.read()
+    filename = os.path.basename(audio_path)
+    mime, _ = mimetypes.guess_type(audio_path)
+    mime = mime or "application/octet-stream"
+
+    parts = []
+    for name, value in (("model", model), ("language", lang),
+                        ("response_format", "text")):
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"'
+            f'\r\n\r\n{value}\r\n'.encode()
+        )
+    parts.append(
+        f'--{boundary}\r\nContent-Disposition: form-data; name="file"; '
+        f'filename="{filename}"\r\nContent-Type: {mime}\r\n\r\n'.encode()
+        + audio_bytes + b'\r\n'
+    )
+    parts.append(f'--{boundary}--\r\n'.encode())
+    body = b"".join(parts)
+
+    req = urllib.request.Request(
+        url, data=body,
+        headers={"Authorization": f"Bearer {key}",
+                 "Content-Type": f"multipart/form-data; boundary={boundary}"},
+        method="POST",
+    )
+    last_err = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            with urllib.request.urlopen(req, timeout=300) as resp:  # nosec B310
+                return resp.read().decode().strip() or None
+        except urllib.error.HTTPError as e:
+            if e.code in (429, 500, 502, 503):
+                last_err = e
+            else:
+                print(f"error: API {e.code}: {e.read().decode()[:300]}",
+                      file=sys.stderr)
+                return None
+        except Exception as e:
+            last_err = e
+        if attempt < MAX_RETRIES - 1:
+            time.sleep(RETRY_DELAYS[attempt])
+    print(f"warn: failed after {MAX_RETRIES} tries: {last_err}", file=sys.stderr)
+    return None
+
+
+# ---------------- main ----------------
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Whispero transcription.")
+    p.add_argument("source", help="Audio file path or YouTube URL (gemini only)")
+    p.add_argument("--provider", default=DEFAULT_PROVIDER,
+                   choices=["gemini", "openai"])
+    p.add_argument("--model", default=None,
+                   help="Model name (default: gemini-2.5-flash / whisper-1)")
+    p.add_argument("--base-url", default=None,
+                   help="Custom API base URL for OpenAI-compatible providers")
+    p.add_argument("--api-key", default=None, help="API key (or env var)")
+    p.add_argument("--fallback-models", default="",
+                   help="Comma-separated fallback models to try in order")
+    p.add_argument("--prompt", default=None)
+    p.add_argument("--lang", default="pt")
+    p.add_argument("--compress", action="store_true",
+                   help="Compress to opus 32k before upload (local files only)")
+    args = p.parse_args()
+
+    key = get_api_key(args)
+    fallbacks = [m.strip() for m in args.fallback_models.split(",") if m.strip()]
+
+    if args.provider == "gemini":
+        model = args.model or DEFAULT_GEMINI_MODEL
+        models = [model] + [m for m in fallbacks if m != model]
+        base = GEMINI_API_BASE
+        prompt = args.prompt or (
+            f"Transcreva este áudio de forma fiel em {args.lang}. "
+            "Retorne apenas a transcrição, sem comentários."
+            if args.lang.startswith("pt")
+            else f"Transcribe this audio faithfully in {args.lang}. "
+                 "Return only the transcript, no commentary."
+        )
+        tmp_path = None
+        if is_url(args.source):
+            media_part = {"file_data": {"file_uri": args.source}}
+        else:
+            if not os.path.isfile(args.source):
+                print(f"error: file not found: {args.source}", file=sys.stderr)
+                return 2
+            src = args.source
+            if args.compress:
+                tmp_path = compress_audio(src)
+                if tmp_path != src:
+                    src = tmp_path
+            try:
+                mime, _ = mimetypes.guess_type(src)
+                mime = mime or "audio/ogg"
+                with open(src, "rb") as fh:
+                    b64 = base64.b64encode(fh.read()).decode("ascii")
+                media_part = {"inline_data": {"mime_type": mime, "data": b64}}
+            finally:
+                if tmp_path and tmp_path != args.source:
+                    os.unlink(tmp_path)
+        for m in models:
+            text = gemini_transcribe(base, key, m, prompt, media_part)
+            if text:
+                print(text)
+                return 0
+            print(f"warn: empty response from {m}, trying next...",
+                  file=sys.stderr)
+    else:  # openai-compatible
+        if is_url(args.source):
+            print("error: URL input only supported with --provider gemini",
+                  file=sys.stderr)
+            return 2
+        if not os.path.isfile(args.source):
+            print(f"error: file not found: {args.source}", file=sys.stderr)
+            return 2
+        model = args.model or DEFAULT_OPENAI_MODEL
+        models = [model] + [m for m in fallbacks if m != model]
+        base = args.base_url or OPENAI_API_BASE
+        src = args.source
+        tmp_path = None
+        if args.compress:
+            tmp_path = compress_audio(src)
+            if tmp_path != src:
+                src = tmp_path
+        try:
+            for m in models:
+                text = openai_transcribe(base, key, m, src, args.lang)
+                if text:
+                    print(text)
+                    return 0
+                print(f"warn: empty response from {m}, trying next...",
+                      file=sys.stderr)
+        finally:
+            if tmp_path and tmp_path != args.source:
+                os.unlink(tmp_path)
+
+    print("error: no usable transcript from any model", file=sys.stderr)
+    return 5
+
+
+if __name__ == "__main__":
+    sys.exit(main())

whispero-0.1.0/whispero.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: whispero
+Version: 0.1.0
+Summary: Universal audio transcription and deep analysis - Gemini native audio plus any OpenAI-compatible API
+Author: Neguiolidas
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Neguiolidas/whispero
+Project-URL: Repository, https://github.com/Neguiolidas/whispero
+Project-URL: Issues, https://github.com/Neguiolidas/whispero/issues
+Keywords: audio,transcription,whisper,speech-to-text,ai-agents,gemini
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Whispero
+
+Audio transcription and deep audio analysis with any OpenAI-compatible
+provider. Defaults to Gemini's native audio input (transcribes *and*
+reasons in one pass); also works with OpenAI, Groq, Together, or any
+Whisper-style `/v1/audio/transcriptions` endpoint.
+
+Unlike pure ASR models, the Gemini path processes audio with reasoning: it
+transcribes, cleans up, structures output, detects speakers, emotions, and
+action items in a single pass.
+
+## Install
+
+```bash
+pip install whispero
+```
+
+## Setup
+
+```bash
+# Gemini (default) - free key at https://aistudio.google.com/apikey
+export GEMINI_API_KEY="your-key-here"
+
+# ...or any provider key, picked up automatically
+export WHISPERO_API_KEY="your-key-here"
+export OPENAI_API_KEY="your-key-here"
+```
+
+## Usage
+
+```bash
+# Simple transcription, Gemini (Portuguese default)
+whispero meeting.mp3
+
+# English transcription
+whispero call.mp3 --lang en
+
+# YouTube URL directly, no download needed (Gemini only)
+whispero "https://www.youtube.com/watch?v=..." --lang en
+whispero-analyze "https://www.youtube.com/watch?v=..."
+
+# OpenAI-compatible provider (Whisper-style API)
+whispero meeting.mp3 --provider openai
+whispero meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1 \
+    --model whisper-large-v3
+
+# Deep analysis: transcript, speakers, tone, emotions, urgency,
+# intent, action items, key moments, irony/sarcasm detection
+whispero-analyze meeting.mp3
+whispero-analyze meeting.mp3 --provider openai \
+    --base-url https://api.groq.com/openai/v1
+
+# Faster upload for large files (compresses to opus 32k first, local files only)
+whispero long.mp3 --compress
+
+# Configurable fallback models (comma-separated, tried in order)
+whispero meeting.mp3 --fallback-models gemini-2.0-flash
+```
+
+## Features
+
+- Two providers: `gemini` (default, native audio + YouTube URLs) and `openai`
+  (any OpenAI-compatible `/v1/audio/transcriptions` endpoint)
+- Speaker diarization ([FALANTE 1], [FALANTE 2] with voice characteristics)
+- Retry with exponential backoff on rate limits and server errors
+- `--fallback-models`: configurable comma-separated fallback list
+- `--compress` flag: converts to opus 32k mono 16kHz via ffmpeg before upload
+- JSON validation on analysis output
+- Zero pip dependencies, only stdlib + ffmpeg
+
+## Benchmark
+
+50 seconds of real audio, Gemini (Portuguese):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~4s | faithful transcript |
+| transcribe.py --compress | ~4s | same, half the upload size |
+| audio_analyze.py | ~14s | full JSON analysis |
+
+GTA 6 trailer via YouTube URL (no download):
+
+| Script | Time | Output |
+|---|---|---|
+| transcribe.py | ~12s | dialogue + song lyrics + on-screen text |
+| audio_analyze.py | ~23s | 4 speakers, tone, 9 key moments, intent |
+
+## License
+
+Apache 2.0 — see LICENSE.

whispero-0.1.0/whispero.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+audio_analyze.py
+pyproject.toml
+transcribe.py
+whispero.egg-info/PKG-INFO
+whispero.egg-info/SOURCES.txt
+whispero.egg-info/dependency_links.txt
+whispero.egg-info/entry_points.txt
+whispero.egg-info/top_level.txt

whispero-0.1.0/whispero.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

whispero-0.1.0/whispero.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+whispero = transcribe:main
+whispero-analyze = audio_analyze:main

whispero-0.1.0/whispero.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+audio_analyze
+transcribe