dvoice-tts 1.0.3

Python client for DVoice TTS API

dvoice-tts-py

A Python client for the DVoice TTS API, providing text-to-speech functionality with support for single audio generation via HTTP and real-time audio streaming over WebSocket.

🚀 Features

• Generate audio files in multiple formats (mp3, wav, ogg, aac, flac).
• Stream audio in real-time for low-latency applications.
• Simple and intuitive API for easy integration.
• Robust error handling for reliable usage.

📦 Installation

Install the package using pip:

pip install dvoice-tts

🧠 Usage

Importing and Initializing

from dvoice_tts import TTS

# Initialize the client with your API token
tts = TTS(token="YOUR_API_TOKEN")

Replace "YOUR_API_TOKEN" with your actual API token from the DVoice TTS service.

Obtaining an API Token

To use the DVoice TTS API, you need a valid API token. Visit the main website at dvoice.uz and navigate to profile.dvoice.uz to create an account or log in. Once logged in, you can generate or retrieve your API token from your profile dashboard.

🔊 Generating a Single Audio File

Use the single() method to generate an audio file from text:

try:
    audio = tts.single(
        model="default",
        text="Salom!",
        format="mp3"  # Options: 'mp3', 'wav', 'ogg', 'aac', 'flac'
    )
    # Save audio to file
    with open("output.mp3", "wb") as f:
        f.write(audio)
    print("Audio file saved as output.mp3")
except Exception as e:
    print(f"Error generating audio: {e}")

🌊 Real-Time Audio Streaming

Use the stream() method to receive audio chunks in real-time over WebSocket:

def on_chunk(err, chunk, close):
    if err:
        print(f"Stream error: {err}")
        close()  # Close the connection on error
    elif chunk:
        # Process the audio chunk (e.g., feed to an audio player)
        print(f"Received audio chunk: {len(chunk)} bytes")
    else:
        # Stream has ended
        print("Stream completed")
        close()  # Close the connection

tts.stream(
    model="default",
    text="Davomiy nutqni real vaqtda translatsiya qilish!",
    format="mp3",  # Options: 'mp3', 'wav', 'ogg', 'aac', 'flac'
    callback=on_chunk
)

The close() function can be called within the callback to terminate the WebSocket connection manually.

📜 API Reference

TTS(token: str)

Creates a new TTS client instance.

• Parameters:
  • token (str): Your API token for DVoice TTS authentication.

tts.single(model: str, text: str, format: str) -> bytes

Generates a single audio file from text via HTTP.

• Parameters:
  • model (str): The TTS model to use (e.g., "default").
  • text (str): The text to convert to speech.
  • format (str): Audio format ("mp3", "wav", "ogg", "aac", "flac").
• Returns: bytes - The audio data as bytes.
• Raises: Exception if the request fails.

tts.stream(model: str, text: str, format: str, callback: Callable[[Optional[Exception], Optional[bytes], Callable[[], None]], None]) -> None

Streams audio chunks in real-time over WebSocket.

• Parameters:
  • model (str): The TTS model to use (e.g., "default").
  • text (str): The text to convert to speech.
  • format (str): Audio format ("mp3", "wav", "ogg", "aac", "flac").
  • callback (Callable): A function that receives (err, chunk, close):
    • err (Exception | None): Any error that occurs.
    • chunk (bytes | None): Audio data chunk, or None if the stream ends.
    • close (Callable): Function to close the WebSocket connection.
• Returns: None

🛠️ Error Handling

Both single() and stream() methods include error handling:

• For single(), errors are raised as exceptions and can be caught using try/except.
• For stream(), errors are passed to the callback as the err parameter.

Example:

try:
    audio = tts.single(model="default", text="Test", format="mp3")
except Exception as e:
    print(f"Failed to generate audio: {e}")

📝 Notes

• Ensure a valid API token is provided to authenticate with the DVoice TTS API.
• The stream() method is suitable for applications requiring real-time audio, such as live voice assistants or interactive systems.
• Refer to the DVoice TTS API documentation for supported models and additional configuration options.
• WebSocket streaming uses the endpoint ws://oyqiz.airi.uz/stream.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🌐 Links

• API Documentation: https://oyqiz.airi.uz/api/v2/tts
• WebSocket Endpoint: ws://oyqiz.airi.uz/stream

🌟 Contributing

Contributions are welcome! Please submit a pull request or open an issue on the GitHub repository for bug reports, feature requests, or improvements.