deepctl-cmd-speak 0.0.3__tar.gz → 0.0.4__tar.gz

{deepctl_cmd_speak-0.0.3 → deepctl_cmd_speak-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-cmd-speak
-Version: 0.0.3
+Version: 0.0.4
 Summary: Speak (text-to-speech) command for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -14,7 +14,7 @@ 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: deepctl-core>=0.2.15
 Requires-Dist: click>=8.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: pydantic>=2.0.0

{deepctl_cmd_speak-0.0.3 → deepctl_cmd_speak-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-speak"
-version = "0.0.3" # x-release-please-version
+version = "0.0.4" # x-release-please-version
 description = "Speak (text-to-speech) command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,7 @@ classifiers = [
 keywords = ["deepgram", "cli", "tts", "text-to-speech", "speak"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl-core>=0.2.15",
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",

{deepctl_cmd_speak-0.0.3 → deepctl_cmd_speak-0.0.4}/src/deepctl_cmd_speak/command.py

@@ -27,6 +27,13 @@ if TYPE_CHECKING:
 
 console = Console(stderr=True)
 
+# Flux (Speak v2) streaming controls, per the /v2/speak API. `speed` is a
+# 0.05-increment multiplier and `expressivity` is a small integer range; both
+# are validated up front so we fail with a clear message instead of surfacing
+# a raw SPEED_OUT_OF_RANGE / server error mid-stream.
+_FLUX_SPEEDS = (0.85, 0.90, 0.95, 1.00, 1.05, 1.10, 1.15)
+_FLUX_EXPRESSIVITY = (-2, -1, 0, 1, 2)
+
 
 def _fmt_bytes(n: int) -> str:
     """Human-readable byte count for progress display."""
@@ -162,26 +169,38 @@ class SpeakCommand(BaseCommand):
     ci_friendly = True
 
     examples = [
+        # Flux TTS is the default (flux-alexis-en) — WebSocket streaming,
+        # raw audio wrapped in WAV. Piped audio is a streaming WAV (unknown
+        # length up front), so pass `-loglevel error` to silence ffmpeg's
+        # cosmetic end-of-stream notice.
         'dg speak "Hello world"',
-        'dg speak "Hello world" -o hello.mp3',
-        "dg speak --file message.txt -o output.mp3",
-        'echo "Hello" | dg speak -o hello.mp3',
-        'dg speak "Hello" | ffplay -nodisp -',
+        'dg speak "Hello world" -o hello.wav',
+        "dg speak --file message.txt -o output.wav",
+        'dg speak "Hello" | ffplay -loglevel error -nodisp -autoexit -',
+        # Flux TTS streaming controls: --speed (0.85-1.15) and beta
+        # --expressivity (-2..2, default 0).
+        'dg speak "A little slower, please" --speed 0.9 -o slow.wav',
+        'dg speak "So exciting!" --expressivity 2 -o lively.wav  # beta; default: 0',
+        # Aura (Speak v1, batch REST) — opt in with -m aura-*; needed for
+        # containerized formats like mp3.
+        'dg speak "Hello" -m aura-2-asteria-en -o hello.mp3',
         'dg speak "Hello" -m aura-2-luna-en -o hello.wav --encoding linear16 --container wav',
-        # Flux TTS — WebSocket streaming (flux-* models), streaming by default.
-        # Piped audio is a streaming WAV (unknown length up front), so pass
-        # `-loglevel error` to silence ffmpeg's cosmetic end-of-stream notice.
-        'dg speak "Hello from Flux" -m flux-alexis-en -o hello.wav',
-        'dg speak "Hello from Flux" -m flux-alexis-en | ffplay -loglevel error -nodisp -autoexit -',
+        'echo "Hello" | dg speak -o hello.mp3 -m aura-2-asteria-en',
+        # Aura-2 Spanish voice (run `dg models` for the full list).
+        'dg speak "Hola, mundo" -m aura-2-selena-es -o hola.mp3',
     ]
     agent_help = (
         "Convert text to speech using Deepgram's TTS API. "
         "Text can be provided as an argument, from a file, or piped via stdin. "
         "Audio is written to a file (--output) or stdout for piping. "
-        "aura-* models use Speak v1 (batch REST). flux-* (Flux TTS) models use "
-        "Speak v2, streaming over WebSocket by default and emitting raw audio; "
-        "linear16 output is wrapped in a WAV container so it is directly playable. "
-        "Supports model selection and audio format options."
+        "By default (flux-* models, e.g. flux-alexis-en) uses Flux TTS / Speak "
+        "v2, streaming over WebSocket and emitting raw audio; linear16 output is "
+        "wrapped in a WAV container so it is directly playable. Pass an aura-* "
+        "model to use Speak v1 (batch REST), which supports containerized "
+        "formats like mp3. Supports model selection and audio format options. "
+        "Flux TTS models also accept --speed (0.85–1.15) and beta "
+        "--expressivity (-2..2; default 0 = nominal) streaming controls; these "
+        "are rejected for other models."
     )
 
     def get_arguments(self) -> list[dict[str, Any]]:
@@ -201,13 +220,13 @@ class SpeakCommand(BaseCommand):
             {
                 "names": ["--model", "-m"],
                 "help": (
-                    "TTS model. aura-* = Speak v1 (REST batch; default "
-                    "aura-2-asteria-en); flux-* = Flux TTS / Speak v2 (WebSocket "
-                    "streaming, e.g. flux-alexis-en)."
+                    "TTS model. flux-* = Flux TTS / Speak v2 (WebSocket "
+                    "streaming; default flux-alexis-en); aura-* = Speak v1 "
+                    "(REST batch, e.g. aura-2-asteria-en)."
                 ),
                 "type": str,
                 "is_option": True,
-                "default": "aura-2-asteria-en",
+                "default": "flux-alexis-en",
             },
             {
                 "names": ["--encoding"],
@@ -234,6 +253,25 @@ class SpeakCommand(BaseCommand):
                 "type": float,
                 "is_option": True,
             },
+            {
+                "names": ["--speed"],
+                "help": (
+                    "Flux TTS (v2) only. Speech-rate multiplier: 0.85, 0.90, 0.95, "
+                    "1.00, 1.05, 1.10, or 1.15 (1.00 = nominal)."
+                ),
+                "type": float,
+                "is_option": True,
+            },
+            {
+                "names": ["--expressivity"],
+                "help": (
+                    "Flux TTS (v2) only, beta. Expressive range: -2, -1, 0, 1, "
+                    "or 2 (default 0 = nominal; negative flatter, positive more "
+                    "animated). Fixed for the connection."
+                ),
+                "type": int,
+                "is_option": True,
+            },
             {
                 "names": ["--file", "-f"],
                 "help": "Read text from file",
@@ -251,10 +289,12 @@ class SpeakCommand(BaseCommand):
     ) -> BaseResult | None:
         text = kwargs.get("text")
         output_path = kwargs.get("output")
-        model = kwargs.get("model") or "aura-2-asteria-en"
+        model = kwargs.get("model") or "flux-alexis-en"
         encoding = kwargs.get("encoding")
         container = kwargs.get("container")
         sample_rate = kwargs.get("sample_rate")
+        speed = kwargs.get("speed")
+        expressivity = kwargs.get("expressivity")
         file_path = kwargs.get("file")
 
         # Resolve text input: arg > --file > stdin
@@ -282,8 +322,29 @@ class SpeakCommand(BaseCommand):
                 message="No output specified. Use -o/--output to save to file, or pipe stdout.",
             )
 
-        # Flux models stream over the WebSocket (speak.v2); Aura uses REST (speak.v1).
-        is_flux = model.lower().startswith("flux")
+        # Only the documented flux-* namespace uses speak.v2. Aura and unknown
+        # model names pass through to the REST API so the service can resolve them.
+        is_flux = model.lower().startswith("flux-")
+
+        # speed / expressivity are Flux (Speak v2) connect controls; reject them
+        # for other models rather than silently dropping them. Raise (not return)
+        # so the failure exits non-zero in every output mode.
+        if not is_flux and (speed is not None or expressivity is not None):
+            raise click.ClickException(
+                "--speed and --expressivity are only supported for Flux TTS "
+                "(Speak v2) models (flux-*). They are not available for "
+                f"Speak v1 model '{model}'."
+            )
+        if speed is not None and speed not in _FLUX_SPEEDS:
+            allowed = ", ".join(f"{s:.2f}" for s in _FLUX_SPEEDS)
+            raise click.ClickException(
+                f"--speed must be one of: {allowed} (got {speed})."
+            )
+        if expressivity is not None and expressivity not in _FLUX_EXPRESSIVITY:
+            allowed = ", ".join(str(e) for e in _FLUX_EXPRESSIVITY)
+            raise click.ClickException(
+                f"--expressivity must be one of: {allowed} (got {expressivity})."
+            )
 
         if is_flux:
             # WebSocket streaming path. Streaming output is raw audio, so
@@ -310,6 +371,8 @@ class SpeakCommand(BaseCommand):
                     model=model,
                     encoding=eff_encoding,
                     sample_rate=eff_sample_rate,
+                    speed=speed,
+                    expressivity=expressivity,
                 )
             )
 
@@ -392,7 +455,7 @@ class SpeakCommand(BaseCommand):
             # to the stderr console.
             return None
 
-        # REST path (Aura v1) — unchanged.
+        # REST path (Speak v1, including Aura and unknown-model pass-through).
         try:
             console.print(f"[blue]Generating speech with {model}...[/blue]")
 
@@ -440,6 +503,11 @@ class SpeakCommand(BaseCommand):
                 # summary above went to the stderr console.
                 return None
 
+        except click.ClickException:
+            raise
         except Exception as e:
-            console.print(f"[red]Error generating speech:[/red] {e}")
-            return BaseResult(status="error", message=str(e))
+            # Raise (not return an error result) so the failure exits non-zero
+            # in every output mode — a returned BaseResult is only printed and
+            # still exits 0. Reachable now that unknown models (e.g. a bare
+            # "flux" typo) route here instead of the raising v2 path.
+            raise click.ClickException(f"Error generating speech: {e}")

{deepctl_cmd_speak-0.0.3 → deepctl_cmd_speak-0.0.4}/src/deepctl_cmd_speak.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-cmd-speak
-Version: 0.0.3
+Version: 0.0.4
 Summary: Speak (text-to-speech) command for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
@@ -14,7 +14,7 @@ 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: deepctl-core>=0.2.15
 Requires-Dist: click>=8.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: pydantic>=2.0.0

{deepctl_cmd_speak-0.0.3 → deepctl_cmd_speak-0.0.4}/src/deepctl_cmd_speak.egg-info/requires.txt

@@ -1,4 +1,4 @@
-deepctl-core>=0.1.10
+deepctl-core>=0.2.15
 click>=8.0.0
 rich>=13.0.0
 pydantic>=2.0.0