livekit-murf 0.1.0__py3-none-any.whl

livekit/plugins/murf/__init__.py

@@ -0,0 +1,31 @@
+"""Murf AI plugin for LiveKit Agents"""
+
+from .tts import TTS, ChunkedStream
+from .version import __version__
+
+__all__ = [
+    "TTS",
+    "ChunkedStream",
+    "__version__",
+]
+
+from livekit.agents import Plugin
+
+from .log import logger
+
+
+class MurfPlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+
+Plugin.register_plugin(MurfPlugin())
+
+# Cleanup docs of unexported modules
+_module = dir()
+NOT_IN_ALL = [m for m in _module if m not in __all__]
+
+__pdoc__ = {}
+
+for n in NOT_IN_ALL:
+    __pdoc__[n] = False

livekit/plugins/murf/log.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("livekit.plugins.murf")

livekit/plugins/murf/models.py

@@ -0,0 +1,61 @@
+from typing import Literal
+
+TTSLocales = Literal[
+    "en-US",
+    "en-UK",
+    "en-AU",
+    "en-IN",
+    "en-SCOTT",
+    "es-ES",
+    "es-MX",
+    "hi-IN",
+    "ta-IN",
+    "bn-IN",
+    "fr-FR",
+    "de-DE",
+    "it-IT",
+    "pt-BR",
+    "zh-CN",
+    "nl-NL",
+    "ja-JP",
+    "id-ID",
+    "ko-KR",
+    "ro-RO",
+    "tr-TR",
+    "pl-PL",
+    "sk-SK",
+    "hr-HR",
+    "el-GR",
+    "bg-BG",
+]
+
+TTSModels = Literal["GEN2", "FALCON"]
+
+TTSStyles = Literal[
+    "Promo",
+    "Narration",
+    "Calm",
+    "Conversation",
+    "Conversational",
+    "Sad",
+    "Angry",
+    "Sports Commentary",
+    "Newscast",
+    "Terrified",
+    "Inspirational",
+    "Customer Support Agent",
+    "Narration",
+    "Audiobook",
+    "Storytelling",
+    "Furious",
+    "Sobbing",
+    "Wizard",
+    "Clown",
+]
+
+TTSEncoding = Literal[
+    "pcm",  # pcm_s16le
+]
+
+TTSDefaultVoiceId = "en-US-matthew"
+TTSDefaultVoiceStyle = "Conversation"

livekit/plugins/murf/py.typed

@@ -0,0 +1 @@
+ 

livekit/plugins/murf/tts.py

@@ -0,0 +1,395 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import os
+import weakref
+from dataclasses import dataclass, replace
+from typing import Any
+
+import aiohttp
+
+from livekit.agents import (
+    APIConnectionError,
+    APIConnectOptions,
+    APIStatusError,
+    APITimeoutError,
+    tokenize,
+    tts,
+    utils,
+)
+from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS, NOT_GIVEN, NotGivenOr
+from livekit.agents.utils import is_given
+
+from .log import logger
+from .models import (
+    TTSDefaultVoiceId,
+    TTSDefaultVoiceStyle,
+    TTSEncoding,
+    TTSLocales,
+    TTSModels,
+    TTSStyles,
+)
+
+API_AUTH_HEADER = "api-key"
+
+
+@dataclass
+class _TTSOptions:
+    api_key: str
+    locale: TTSLocales | str | None
+    model: TTSModels | str
+    voice: str
+    style: str | None
+    speed: int | None
+    pitch: int | None
+    sample_rate: int
+    encoding: TTSEncoding
+    base_url: str
+
+    def get_http_url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def get_ws_url(self, path: str) -> str:
+        return f"{self.base_url.replace('http', 'ws', 1)}{path}"
+
+
+class TTS(tts.TTS):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: TTSModels | str = "FALCON",
+        locale: TTSLocales | str | None = None,
+        voice: str = TTSDefaultVoiceId,
+        style: TTSStyles | str | None = None,
+        speed: int | None = None,
+        pitch: int | None = None,
+        sample_rate: int = 24000,
+        encoding: TTSEncoding = "pcm",
+        base_url: str = "https://global.api.murf.ai",
+        http_session: aiohttp.ClientSession | None = None,
+        tokenizer: NotGivenOr[tokenize.SentenceTokenizer] = NOT_GIVEN,
+        text_pacing: tts.SentenceStreamPacer | bool = False,
+    ) -> None:
+        """
+        Create a new instance of Murf AI TTS.
+
+        See https://murf.ai/api/docs/api-reference/text-to-speech/stream-input for more details on the the Murf AI API.
+
+        Args:
+            api_key (str | None, optional): The Murf AI API key. If not provided, it will be read from the MURF_API_KEY environment variable.
+            model (TTSModels | str, optional): The Murf AI TTS model to use. Defaults to "FALCON".
+            locale (str | None, optional): The locale for synthesis (e.g., "en-US", "en-UK"). If not provided, will be inferred from voice.
+            voice (str, optional): The voice ID from Murf AI's voice library (e.g., "en-US-matthew"). Defaults to TTSDefaultVoiceId.
+            style (TTSStyles | str | None, optional): The voice style to apply (e.g., "Conversation"). Can be None for default style.
+            speed (int | None, optional): The speech speed control. Higher values = faster speech. None for default speed.
+            pitch (int | None, optional): The speech pitch control. Higher values = higher pitch. None for default pitch.
+            sample_rate (int, optional): The audio sample rate in Hz. Defaults to 24000.
+            encoding (str, optional): The audio encoding format. Defaults to "pcm".
+            http_session (aiohttp.ClientSession | None, optional): An existing aiohttp ClientSession to use. If not provided, a new session will be created.
+            base_url (str, optional): The base URL for the Murf AI API. Defaults to "https://global.api.murf.ai".
+            tokenizer (tokenize.SentenceTokenizer, optional): The tokenizer to use. Defaults to tokenize.basic.SentenceTokenizer(min_sentence_len=BUFFERED_WORDS_COUNT).
+            text_pacing (tts.SentenceStreamPacer | bool, optional): Stream pacer for the TTS. Set to True to use the default pacer, False to disable.
+        """  # noqa: E501
+
+        super().__init__(
+            capabilities=tts.TTSCapabilities(streaming=True),
+            sample_rate=sample_rate,
+            num_channels=1,
+        )
+
+        murf_api_key = api_key or os.environ.get("MURF_API_KEY")
+        if not murf_api_key:
+            raise ValueError("MURF_API_KEY must be set")
+
+        self._opts = _TTSOptions(
+            api_key=murf_api_key,
+            model=model,
+            locale=locale,
+            voice=voice,
+            style=style or TTSDefaultVoiceStyle,
+            speed=speed,
+            pitch=pitch,
+            sample_rate=sample_rate,
+            encoding=encoding,
+            base_url=base_url,
+        )
+        self._session = http_session
+        self._pool = utils.ConnectionPool[aiohttp.ClientWebSocketResponse](
+            connect_cb=self._connect_ws,
+            close_cb=self._close_ws,
+            max_session_duration=300,
+            mark_refreshed_on_get=True,
+        )
+        self._streams = weakref.WeakSet[SynthesizeStream]()
+        self._sentence_tokenizer = (
+            tokenizer if is_given(tokenizer) else tokenize.blingfire.SentenceTokenizer()
+        )
+        self._stream_pacer: tts.SentenceStreamPacer | None = None
+        if text_pacing is True:
+            self._stream_pacer = tts.SentenceStreamPacer()
+        elif isinstance(text_pacing, tts.SentenceStreamPacer):
+            self._stream_pacer = text_pacing
+
+    @property
+    def model(self) -> str:
+        return self._opts.model
+
+    @property
+    def provider(self) -> str:
+        return "Murf"
+
+    async def _connect_ws(self, timeout: float) -> aiohttp.ClientWebSocketResponse:
+        session = self._ensure_session()
+        url = self._opts.get_ws_url(
+            f"/v1/speech/stream-input?api-key={self._opts.api_key}&sample_rate={self._opts.sample_rate}&format={self._opts.encoding}&model={self._opts.model}"
+        )
+        return await asyncio.wait_for(session.ws_connect(url), timeout)
+
+    async def _close_ws(self, ws: aiohttp.ClientWebSocketResponse) -> None:
+        await ws.close()
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if not self._session:
+            self._session = utils.http_context.http_session()
+
+        return self._session
+
+    def prewarm(self) -> None:
+        self._pool.prewarm()
+
+    def update_options(
+        self,
+        *,
+        locale: NotGivenOr[str] = NOT_GIVEN,
+        voice: NotGivenOr[str] = NOT_GIVEN,
+        style: NotGivenOr[str | None] = NOT_GIVEN,
+        speed: NotGivenOr[int | None] = NOT_GIVEN,
+        pitch: NotGivenOr[int | None] = NOT_GIVEN,
+    ) -> None:
+        """
+        Update the Text-to-Speech (TTS) configuration options.
+
+        This method allows updating the TTS settings, including model, locale, voice, style,
+        speed and pitch. If any parameter is not provided, the existing value will be retained.
+
+        Args:
+            locale (str, optional): The locale for synthesis (e.g., "en-US", "en-UK").
+            voice (str, optional): The voice ID from Murf AI's voice library. (e.g. "en-US-matthew")
+            style (str | None, optional): The voice style to apply (e.g., "Conversation", "Promo").
+            speed (int | None, optional): Controls the speech speed. Positive values increase speed, negative values decrease it. Valid range: -50 to 50.
+            pitch (int | None, optional): Controls the speech pitch. Positive values raise pitch, negative values lower it. Valid range: -50 to 50.
+        """
+        if is_given(locale):
+            self._opts.locale = locale
+        if is_given(voice):
+            self._opts.voice = voice
+        if is_given(style):
+            self._opts.style = style
+        if is_given(speed):
+            self._opts.speed = speed
+        if is_given(pitch):
+            self._opts.pitch = pitch
+
+    def synthesize(
+        self, text: str, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
+    ) -> ChunkedStream:
+        return ChunkedStream(tts=self, input_text=text, conn_options=conn_options)
+
+    def stream(
+        self, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
+    ) -> SynthesizeStream:
+        stream = SynthesizeStream(tts=self, conn_options=conn_options)
+        self._streams.add(stream)
+        return stream
+
+    async def aclose(self) -> None:
+        for stream in list(self._streams):
+            await stream.aclose()
+
+        self._streams.clear()
+        await self._pool.aclose()
+
+
+class ChunkedStream(tts.ChunkedStream):
+    """Synthesize chunked text using the http streaming output endpoint"""
+
+    def __init__(self, *, tts: TTS, input_text: str, conn_options: APIConnectOptions) -> None:
+        super().__init__(tts=tts, input_text=input_text, conn_options=conn_options)
+        self._tts: TTS = tts
+        self._opts = replace(tts._opts)
+
+    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
+        try:
+            async with self._tts._ensure_session().post(
+                self._opts.get_http_url("/v1/speech/stream"),
+                headers={API_AUTH_HEADER: self._opts.api_key},
+                json={
+                    "text": self._input_text,
+                    "model": self._opts.model,
+                    "multiNativeLocale": self._opts.locale,
+                    "voice_id": self._opts.voice,
+                    "style": self._opts.style,
+                    "rate": self._opts.speed,
+                    "pitch": self._opts.pitch,
+                    "format": self._opts.encoding,
+                    "sample_rate": self._opts.sample_rate,
+                },
+                timeout=aiohttp.ClientTimeout(total=30, sock_connect=self._conn_options.timeout),
+            ) as resp:
+                resp.raise_for_status()
+
+                output_emitter.initialize(
+                    request_id=utils.shortuuid(),
+                    sample_rate=self._opts.sample_rate,
+                    num_channels=1,
+                    mime_type="audio/pcm",
+                )
+
+                async for data, _ in resp.content.iter_chunks():
+                    output_emitter.push(data)
+
+                output_emitter.flush()
+        except asyncio.TimeoutError:
+            raise APITimeoutError() from None
+        except aiohttp.ClientResponseError as e:
+            raise APIStatusError(
+                message=e.message, status_code=e.status, request_id=None, body=None
+            ) from None
+        except Exception as e:
+            raise APIConnectionError() from e
+
+
+class SynthesizeStream(tts.SynthesizeStream):
+    def __init__(self, *, tts: TTS, conn_options: APIConnectOptions):
+        super().__init__(tts=tts, conn_options=conn_options)
+        self._tts: TTS = tts
+        self._opts = replace(tts._opts)
+
+    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
+        request_id = utils.shortuuid()
+        output_emitter.initialize(
+            request_id=request_id,
+            sample_rate=self._opts.sample_rate,
+            num_channels=1,
+            mime_type="audio/pcm",
+            stream=True,
+        )
+
+        input_sent_event = asyncio.Event()
+
+        sent_tokenizer_stream = self._tts._sentence_tokenizer.stream()
+        if self._tts._stream_pacer:
+            sent_tokenizer_stream = self._tts._stream_pacer.wrap(
+                sent_stream=sent_tokenizer_stream,
+                audio_emitter=output_emitter,
+            )
+
+        async def _sentence_stream_task(ws: aiohttp.ClientWebSocketResponse) -> None:
+            context_id = utils.shortuuid()
+            base_pkt = _to_murf_websocket_pkt(self._opts)
+            async for ev in sent_tokenizer_stream:
+                token_pkt = base_pkt.copy()
+                token_pkt["context_id"] = context_id
+                token_pkt["text"] = ev.token + " "
+                self._mark_started()
+                await ws.send_str(json.dumps(token_pkt))
+                input_sent_event.set()
+
+            end_pkt = base_pkt.copy()
+            end_pkt["context_id"] = context_id
+            end_pkt["end"] = True
+            await ws.send_str(json.dumps(end_pkt))
+            input_sent_event.set()
+
+        async def _input_task() -> None:
+            async for data in self._input_ch:
+                if isinstance(data, self._FlushSentinel):
+                    sent_tokenizer_stream.flush()
+                    continue
+
+                sent_tokenizer_stream.push_text(data)
+
+            sent_tokenizer_stream.end_input()
+
+        async def _recv_task(ws: aiohttp.ClientWebSocketResponse) -> None:
+            current_segment_id: str | None = None
+            await input_sent_event.wait()
+            while True:
+                msg = await ws.receive()
+                if msg.type in (
+                    aiohttp.WSMsgType.CLOSED,
+                    aiohttp.WSMsgType.CLOSE,
+                    aiohttp.WSMsgType.CLOSING,
+                ):
+                    raise APIStatusError(
+                        "Murf AI connection closed unexpectedly", request_id=request_id
+                    )
+
+                if msg.type != aiohttp.WSMsgType.TEXT:
+                    logger.warning("unexpected Murf AI message type %s", msg.type)
+                    continue
+
+                data = json.loads(msg.data)
+                segment_id = data.get("context_id")
+                if current_segment_id is None:
+                    current_segment_id = segment_id
+                    output_emitter.start_segment(segment_id=current_segment_id)
+                if data.get("audio"):
+                    b64data = base64.b64decode(data["audio"])
+                    output_emitter.push(b64data)
+                elif data.get("final"):
+                    if sent_tokenizer_stream.closed:
+                        # close only if the input stream is closed
+                        output_emitter.end_input()
+                        break
+                else:
+                    logger.warning("unexpected message %s", data)
+
+        try:
+            async with self._tts._pool.connection(timeout=self._conn_options.timeout) as ws:
+                tasks = [
+                    asyncio.create_task(_input_task()),
+                    asyncio.create_task(_sentence_stream_task(ws)),
+                    asyncio.create_task(_recv_task(ws)),
+                ]
+
+                try:
+                    await asyncio.gather(*tasks)
+                finally:
+                    input_sent_event.set()
+                    await sent_tokenizer_stream.aclose()
+                    await utils.aio.gracefully_cancel(*tasks)
+        except asyncio.TimeoutError:
+            raise APITimeoutError() from None
+        except aiohttp.ClientResponseError as e:
+            raise APIStatusError(
+                message=e.message, status_code=e.status, request_id=None, body=None
+            ) from None
+        except Exception as e:
+            raise APIConnectionError() from e
+
+
+def _to_murf_websocket_pkt(opts: _TTSOptions) -> dict[str, Any]:
+    voice_config: dict[str, Any] = {}
+
+    if opts.voice:
+        voice_config["voice_id"] = opts.voice
+
+    if opts.style:
+        voice_config["style"] = opts.style
+
+    if opts.speed:
+        voice_config["rate"] = opts.speed
+
+    if opts.pitch:
+        voice_config["pitch"] = opts.pitch
+
+    if opts.locale:
+        voice_config["multi_native_locale"] = opts.locale
+
+    return {
+        "voice_config": voice_config,
+    }

livekit/plugins/murf/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

livekit_murf-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: livekit-murf
+Version: 0.1.0
+Summary: LiveKit Agents Plugin for Murf
+Project-URL: Repository, https://github.com/murf-ai/livekit-murf
+Project-URL: Issues, https://github.com/murf-ai/livekit-murf/issues
+Author-email: Gaurav Singh <gaurav.singh@murf.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,livekit,realtime,webrtc
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9.0
+Requires-Dist: livekit-agents>=1.2.18
+Description-Content-Type: text/markdown
+
+# Livekit Murf
+
+![Murf AI Logo](https://murf.ai/public-assets/home/Murf_Logo.png)
+
+
+Official [Murf AI](https://murf.ai/api) Text-to-Speech integration for [Livekit Agents](https://github.com/livekit/agents) - a framework for building voice and multimodal conversational AI applications.
+
+> **Note**: This integration is maintained by Murf AI. As the official provider of the TTS service, we are committed to actively maintaining and updating this integration.
+
+
+## Installation
+
+```bash
+pip install livekit-murf
+```
+
+## Livekit Starter Project 
+
+```python
+from livekit.agents import JobContext, WorkerOptions, cli, JobProcess, get_job_context
+from livekit.agents.voice import Agent, AgentSession
+from livekit.plugins import murf, openai, silero, deepgram
+
+class MyAgent(Agent):
+    def __init__(self) -> None:
+        super().__init__(
+            instructions="You are a voice agent build using Murf TTS",
+            stt=deepgram.STT(model="nova-3"),
+            llm=openai.LLM(model="gpt-4o"),
+            tts=murf.TTS(voice="en-US-matthew", style="Conversation"),
+            vad=get_job_context().proc.userdata["vad"],
+        )
+
+    async def on_enter(self):
+        await self.session.say("Hi, I am a voice agent powered by Murf, how can I help you?")
+
+
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+    ctx.log_context_fields = {
+        "room": ctx.room.name,
+    }
+
+    session = AgentSession()
+
+    await session.start(
+        agent=MyAgent(),
+        room=ctx.room
+    )
+
+
+def prewarm(proc: JobProcess):
+    proc.userdata["vad"] = silero.VAD.load()
+
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm))
+```
+
+## Pre-requisites
+
+You'll need an API key from [Murf AI](https://murf.ai/api). It can be set as an environment variable: `MURF_API_KEY` 
+
+> **Compatibility**: Requires livekit-agents >= 1.2.18.

livekit_murf-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+livekit/plugins/murf/__init__.py,sha256=-y_AiQO-b7sqLl5hHk2M5WJCJVyZelw4MtfBc8R_dDM,573
+livekit/plugins/murf/log.py,sha256=hHPw7aKUXZOW4QTgK0kj-csrPMhKoQrVb1TuMazyeF0,67
+livekit/plugins/murf/models.py,sha256=vP7BlBW7JsgWpMkLeEfCG6R9IdysRN3f4dGVJM6jS9s,909
+livekit/plugins/murf/py.typed,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
+livekit/plugins/murf/tts.py,sha256=Y4tqmxxNbA2EzDPJ4ufymuMto6RL2TCfslVbci9Upps,15051
+livekit/plugins/murf/version.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+livekit_murf-0.1.0.dist-info/METADATA,sha256=ycxgB8gVHBV0O6bFCNkAqS2pHXJQld7BYDjlHPWqdy4,2826
+livekit_murf-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+livekit_murf-0.1.0.dist-info/licenses/LICENSE,sha256=SxRdfCVAmnkiSsVHJHhXmRX0yqidcRlBMjy-R2GZFdM,1066
+livekit_murf-0.1.0.dist-info/RECORD,,

livekit_murf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

livekit_murf-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Murf Inc.
+
+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.