deepctl-cmd-debug-audio 0.1.10__tar.gz → 0.1.11__tar.gz

deepctl_cmd_debug_audio-0.1.11/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: deepctl-cmd-debug-audio
+Version: 0.1.11
+Summary: Audio debug subcommand for deepctl
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,debug,audio,diagnostics
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: httpx>=0.24.0
+
+# deepctl-cmd-debug-audio
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Audio debug subcommand for deepctl
+
+This is a subcommand of `deepctl debug`.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `deepctl debug audio` | `deepctl_cmd_debug_audio.command:AudioCommand` |
+
+## Dependencies
+
+- `click>=8.0.0`
+- `rich>=13.0.0`
+- `pydantic>=2.0.0`
+- `ffmpeg-python>=0.2.0`
+- `httpx>=0.24.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

deepctl_cmd_debug_audio-0.1.11/README.md

@@ -0,0 +1,46 @@
+# deepctl-cmd-debug-audio
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Audio debug subcommand for deepctl
+
+This is a subcommand of `deepctl debug`.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `deepctl debug audio` | `deepctl_cmd_debug_audio.command:AudioCommand` |
+
+## Dependencies
+
+- `click>=8.0.0`
+- `rich>=13.0.0`
+- `pydantic>=2.0.0`
+- `ffmpeg-python>=0.2.0`
+- `httpx>=0.24.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

{deepctl_cmd_debug_audio-0.1.10 → deepctl_cmd_debug_audio-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-audio"
-version = "0.1.10"
+version = "0.1.11" # x-release-please-version
 description = "Audio debug subcommand for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = [
     "rich>=13.0.0",
     "pydantic>=2.0.0",
     "ffmpeg-python>=0.2.0",
+    "httpx>=0.24.0",
 ]
 
 [project.scripts]

{deepctl_cmd_debug_audio-0.1.10 → deepctl_cmd_debug_audio-0.1.11}/src/deepctl_cmd_debug_audio/command.py

@@ -1,11 +1,15 @@
 """Audio debug command for deepctl."""
 
 import json
+import os
 import shutil
 import subprocess
+import tempfile
 from typing import Any
+from urllib.parse import urlparse
 
 import ffmpeg  # type: ignore[import-untyped]
+import httpx
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
 from rich import box
 from rich.console import Console
@@ -24,6 +28,17 @@ class AudioCommand(BaseCommand):
     help = "Debug audio file issues for Deepgram transcription"
     short_help = "Debug audio issues"
 
+    examples = [
+        "dg debug audio recording.wav",
+        "dg debug audio https://example.com/audio.mp3",
+        "dg debug audio podcast.mp3 --verbose",
+    ]
+    agent_help = (
+        "Analyze audio files for compatibility with Deepgram's transcription "
+        "API. Reports format, codec, sample rate, channels, and duration. "
+        "Flags issues that may cause transcription failures."
+    )
+
     # Audio debug doesn't require auth
     requires_auth = False
     requires_project = False
@@ -54,8 +69,7 @@ class AudioCommand(BaseCommand):
             {
                 "names": ["--ffprobe-args"],
                 "help": (
-                    "Custom ffprobe arguments "
-                    "(e.g., '-show_streams -show_format')"
+                    "Custom ffprobe arguments (e.g., '-show_streams -show_format')"
                 ),
                 "type": str,
                 "is_option": True,
@@ -66,6 +80,113 @@ class AudioCommand(BaseCommand):
         """Check if ffmpeg/ffprobe is installed."""
         return shutil.which("ffprobe") is not None
 
+    def _is_url(self, path: str) -> bool:
+        """Check if the path is a URL."""
+        parsed = urlparse(path)
+        return parsed.scheme in ("http", "https")
+
+    def _download_url(self, url: str) -> str:
+        """Download a URL to a temporary file and return the path."""
+        console.print(f"[blue]Downloading:[/blue] {url}")
+
+        parsed = urlparse(url)
+        ext = os.path.splitext(parsed.path)[1] or ".audio"
+
+        with tempfile.NamedTemporaryFile(
+            suffix=ext, prefix="deepctl_audio_", delete=False
+        ) as tmp:
+            tmp_name = tmp.name
+            try:
+                with (
+                    httpx.Client(timeout=60.0, follow_redirects=True) as client,
+                    client.stream("GET", url) as response,
+                ):
+                    response.raise_for_status()
+                    total = 0
+                    for chunk in response.iter_bytes(chunk_size=8192):
+                        tmp.write(chunk)
+                        total += len(chunk)
+                size_mb = total / (1024 * 1024)
+                console.print(
+                    f"[green]Downloaded[/green] {size_mb:.2f} MB → {tmp_name}"
+                )
+                return tmp_name
+            except Exception:
+                os.unlink(tmp_name)
+                raise
+
+    def _suggest_encoding(self, audio_info: AudioInfo) -> None:
+        """Suggest optimal Deepgram settings based on audio analysis."""
+        if not audio_info.streams:
+            return
+
+        console.print("\n[bold]Encoding Suggestions:[/bold]")
+
+        stream = audio_info.streams[0]
+        suggestions = []
+
+        # Sample rate suggestions
+        if stream.sample_rate:
+            rate = int(stream.sample_rate)
+            if rate == 8000:
+                suggestions.append(
+                    "Telephony audio detected (8kHz) — "
+                    "use `encoding=mulaw` or `encoding=linear16` "
+                    "with `sample_rate=8000`"
+                )
+            elif rate <= 16000:
+                suggestions.append(
+                    f"Sample rate {rate}Hz — suitable for speech. "
+                    f"Consider `encoding=linear16` with "
+                    f"`sample_rate={rate}`"
+                )
+            elif rate >= 44100:
+                suggestions.append(
+                    f"High sample rate ({rate}Hz) — "
+                    f"downsampling to 16kHz is recommended for "
+                    f"faster processing without quality loss"
+                )
+
+        # Codec suggestions
+        if stream.codec_name:
+            codec = stream.codec_name.lower()
+            if codec == "opus":
+                suggestions.append(
+                    "Opus codec detected — ideal for web streaming. Use `encoding=opus`"
+                )
+            elif codec in ("pcm_s16le", "pcm_s16be"):
+                suggestions.append("Linear PCM detected — use `encoding=linear16`")
+            elif codec in ("pcm_mulaw", "pcm_alaw"):
+                enc = "mulaw" if "mulaw" in codec else "alaw"
+                suggestions.append(f"{codec} detected — use `encoding={enc}`")
+            elif codec == "mp3":
+                suggestions.append(
+                    "MP3 detected — Deepgram handles MP3 natively. "
+                    "No encoding parameter needed for pre-recorded."
+                )
+            elif codec in ("flac", "vorbis", "aac"):
+                suggestions.append(
+                    f"{codec.upper()} detected — Deepgram handles "
+                    f"this natively for pre-recorded. For streaming, "
+                    f"consider converting to linear16 or opus."
+                )
+
+        # Channel suggestions
+        if stream.channels and stream.channels > 1:
+            suggestions.append(
+                f"Multi-channel ({stream.channels}ch) — use "
+                f"`channels={stream.channels}` and consider "
+                f"`multichannel=true` for speaker separation"
+            )
+        elif stream.channels == 1:
+            suggestions.append("Mono audio — optimal for single-speaker transcription")
+
+        if suggestions:
+            for suggestion in suggestions:
+                console.print(f"  [dim]→[/dim] {suggestion}")
+        else:
+            console.print("  [green]No specific encoding changes needed[/green]")
+
     def run_ffprobe(
         self, file_path: str, custom_args: str | None = None
     ) -> dict[str, Any]:
@@ -106,9 +227,7 @@ class AudioCommand(BaseCommand):
                     else None
                 ),
                 size=(
-                    int(format_data.get("size", 0))
-                    if format_data.get("size")
-                    else None
+                    int(format_data.get("size", 0)) if format_data.get("size") else None
                 ),
                 bit_rate=format_data.get("bit_rate"),
                 nb_streams=(
@@ -156,9 +275,7 @@ class AudioCommand(BaseCommand):
 
             if audio_info.format.duration:
                 minutes, seconds = divmod(audio_info.format.duration, 60)
-                console.print(
-                    f"  • Duration: {int(minutes):02d}:{seconds:06.3f}"
-                )
+                console.print(f"  • Duration: {int(minutes):02d}:{seconds:06.3f}")
 
             if audio_info.format.size:
                 size_mb = audio_info.format.size / (1024 * 1024)
@@ -174,9 +291,7 @@ class AudioCommand(BaseCommand):
             for i, stream in enumerate(audio_info.streams):
                 if len(audio_info.streams) > 1:
                     console.print(f"\n  Stream {i + 1}:")
-                codec_name = (
-                    stream.codec_long_name or stream.codec_name or "Unknown"
-                )
+                codec_name = stream.codec_long_name or stream.codec_name or "Unknown"
                 console.print(f"  • Codec: {codec_name}")
                 if stream.sample_rate:
                     console.print(f"  • Sample Rate: {stream.sample_rate} Hz")
@@ -187,9 +302,7 @@ class AudioCommand(BaseCommand):
                     )
                 if stream.bit_rate:
                     bit_rate_kbps = int(stream.bit_rate) / 1000
-                    console.print(
-                        f"  • Stream Bit Rate: {bit_rate_kbps:.0f} kbps"
-                    )
+                    console.print(f"  • Stream Bit Rate: {bit_rate_kbps:.0f} kbps")
 
     def display_verbose_info(self, audio_info: AudioInfo) -> None:
         """Display detailed audio information in table format."""
@@ -248,9 +361,7 @@ class AudioCommand(BaseCommand):
                             display_value = f"{bit_rate_kbps:.0f} kbps"
                         elif key == "duration" and value:
                             minutes, seconds = divmod(value, 60)
-                            display_value = (
-                                f"{int(minutes):02d}:{seconds:06.3f}"
-                            )
+                            display_value = f"{int(minutes):02d}:{seconds:06.3f}"
 
                         stream_table.add_row(display_key, display_value)
 
@@ -268,9 +379,7 @@ class AudioCommand(BaseCommand):
             from rich.syntax import Syntax
 
             json_str = json.dumps(audio_info.raw_data, indent=2)
-            syntax = Syntax(
-                json_str, "json", theme="monokai", line_numbers=True
-            )
+            syntax = Syntax(json_str, "json", theme="monokai", line_numbers=True)
             console.print(syntax)
 
     def handle(
@@ -320,12 +429,35 @@ class AudioCommand(BaseCommand):
                 ffmpeg_installed=False,
             )
 
+        # Handle URL downloads
+        downloaded_file = None
+        file_to_analyze = str(audio_file)
+
+        if self._is_url(audio_file):
+            try:
+                downloaded_file = self._download_url(audio_file)
+                file_to_analyze = downloaded_file
+            except Exception as e:
+                console.print(
+                    Panel(
+                        f"[red]✗ Failed to download URL[/red]\n\n[dim]{e!s}[/dim]",
+                        title="Download Failed",
+                        border_style="red",
+                    )
+                )
+                return AudioDebugResult(
+                    status="error",
+                    message="Failed to download audio URL",
+                    audio_file=audio_file,
+                    error_details=str(e),
+                )
+
         # Process the audio file
         try:
-            console.print(f"[blue]Analyzing audio file:[/blue] {audio_file}")
+            console.print(f"[blue]Analyzing audio file:[/blue] {file_to_analyze}")
 
             # Run ffprobe
-            probe_data = self.run_ffprobe(str(audio_file), ffprobe_args)
+            probe_data = self.run_ffprobe(file_to_analyze, ffprobe_args)
 
             # Parse the data
             audio_info = self.parse_audio_info(probe_data)
@@ -364,10 +496,12 @@ class AudioCommand(BaseCommand):
                     console.print(f"  {issue}")
             else:
                 console.print(
-                    "  [green]✓[/green] Audio appears to be compatible "
-                    "with Deepgram"
+                    "  [green]✓[/green] Audio appears to be compatible with Deepgram"
                 )
 
+            # Encoding suggestions
+            self._suggest_encoding(audio_info)
+
             return AudioDebugResult(
                 status="success",
                 message="Audio file analyzed successfully",
@@ -378,8 +512,7 @@ class AudioCommand(BaseCommand):
         except Exception as e:
             console.print(
                 Panel(
-                    f"[red]✗ Error analyzing audio file[/red]\n\n"
-                    f"[dim]{e!s}[/dim]",
+                    f"[red]✗ Error analyzing audio file[/red]\n\n[dim]{e!s}[/dim]",
                     title="Analysis Failed",
                     border_style="red",
                 )
@@ -391,3 +524,10 @@ class AudioCommand(BaseCommand):
                 audio_file=audio_file,
                 error_details=str(e),
             )
+        finally:
+            # Clean up downloaded file
+            if downloaded_file:
+                try:
+                    os.unlink(downloaded_file)
+                except OSError:
+                    pass

deepctl_cmd_debug_audio-0.1.11/src/deepctl_cmd_debug_audio.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: deepctl-cmd-debug-audio
+Version: 0.1.11
+Summary: Audio debug subcommand for deepctl
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,debug,audio,diagnostics
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: httpx>=0.24.0
+
+# deepctl-cmd-debug-audio
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Audio debug subcommand for deepctl
+
+This is a subcommand of `deepctl debug`.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `deepctl debug audio` | `deepctl_cmd_debug_audio.command:AudioCommand` |
+
+## Dependencies
+
+- `click>=8.0.0`
+- `rich>=13.0.0`
+- `pydantic>=2.0.0`
+- `ffmpeg-python>=0.2.0`
+- `httpx>=0.24.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

{deepctl_cmd_debug_audio-0.1.10 → deepctl_cmd_debug_audio-0.1.11}/src/deepctl_cmd_debug_audio.egg-info/requires.txt

@@ -3,3 +3,4 @@ click>=8.0.0
 rich>=13.0.0
 pydantic>=2.0.0
 ffmpeg-python>=0.2.0
+httpx>=0.24.0

deepctl_cmd_debug_audio-0.1.10/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: deepctl-cmd-debug-audio
-Version: 0.1.10
-Summary: Audio debug subcommand for deepctl
-Author-email: Deepgram <devrel@deepgram.com>
-Maintainer-email: Deepgram <devrel@deepgram.com>
-License-Expression: MIT
-Keywords: deepgram,cli,debug,audio,diagnostics
-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
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: click>=8.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: ffmpeg-python>=0.2.0
-
-# deepctl-cmd-debug-audio
-
-Audio debug subcommand for the Deepgram CLI (deepctl). This package provides the `audio` subcommand under the `debug` command group, allowing users to debug audio-related issues using ffprobe presets.
-
-`ffmpeg` is required.

deepctl_cmd_debug_audio-0.1.10/README.md

@@ -1,5 +0,0 @@
-# deepctl-cmd-debug-audio
-
-Audio debug subcommand for the Deepgram CLI (deepctl). This package provides the `audio` subcommand under the `debug` command group, allowing users to debug audio-related issues using ffprobe presets.
-
-`ffmpeg` is required.

deepctl_cmd_debug_audio-0.1.10/src/deepctl_cmd_debug_audio.egg-info/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: deepctl-cmd-debug-audio
-Version: 0.1.10
-Summary: Audio debug subcommand for deepctl
-Author-email: Deepgram <devrel@deepgram.com>
-Maintainer-email: Deepgram <devrel@deepgram.com>
-License-Expression: MIT
-Keywords: deepgram,cli,debug,audio,diagnostics
-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
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: click>=8.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: ffmpeg-python>=0.2.0
-
-# deepctl-cmd-debug-audio
-
-Audio debug subcommand for the Deepgram CLI (deepctl). This package provides the `audio` subcommand under the `debug` command group, allowing users to debug audio-related issues using ffprobe presets.
-
-`ffmpeg` is required.