Domain: https://agents.monkeyenglish.net/
APIKEY: a813ec766197294184a938c331b08e7g

Translate Text API

Endpoint:

POST /translate

Description:

This endpoint translates text from a source language to a target language. It supports both basic and advanced translation, with additional options for context, area, and style in the advanced mode.

Request Headers:

Request Body:

Basic Translation:

Note: source_lang, target_lang có thể sử dụng tên quốc gia, hoặc code tên quốc gia theo bảng.

Advanced Translation (with additional optional fields):

Example Request (Basic Translation):

{
  "source_lang": "en",
  "target_lang": "es",
  "sentence": "Hello, how are you?",
  "is_advance": false
}

Example Response

{
  "message": "success",
  "target": "Humanity is truly terrifying.",
  "audio_target": "",
  "data": {
    "vie": {
      "text": "Nhân loại thực sự đáng sợ.",
      "audio": "https://vnmedia2.monkeyuni.net/App/uploads/productivity/TW4TBoru1K0TAneo7qUc.wav"
    },
    "eng": {
      "text": "Humanity is truly terrifying.",
      "audio": "https://vnmedia2.monkeyuni.net/App/uploads/productivity/h41XWUypOsAOIWUvWvvW.wav"
    }
  }
}

Supported Languages:

Speech Translation API

Endpoint:

POST /speech/translate

Description:

This endpoint translates an uploaded audio file from a source language to a target language. It supports speech-to-text translation tasks.

Request Headers:

Request Body (Form-Data):

Example Request (Form-Data):

Note: Language code follows the above table.
Task: S2TT if only want to translate to text, S2ST to translate with output audio + text
target: accept multi-output Example "vie,eng,spa"

Response:

Successful Response (200 OK):

{
  "status": "success",
  "output": "Bonjour",
  "error": ""
}

Error Response (500 Internal Server Error):

{
  "status": "failure",
  "output": "",
  "error": "System encountered an unexpected error. <error message>"
}

Error Handling:

• 401 Unauthorized: Invalid API key.
• 500 Internal Server Error: System encountered an unexpected error.

Audio Streaming Client for Speech-to-Text and Translation (S2TT)

1. Overview

This document provides an overview of how to implement a client for streaming audio data to a WebSocket server that processes the data for speech-to-text-to-translation (S2TT) tasks. The system is designed to handle real-time audio streaming from clients, which can be built using various programming languages.

Key Components:

• WebSocket Server: The server receives audio data from the client, processes it, and returns results (e.g., transcriptions, translations).
• Client: Any client application (mobile, desktop, web) can stream audio to the server over WebSocket.
• Streaming Protocol: Audio data is chunked and transmitted in real-time, with metadata indicating task details such as the source language, target language, and processing task.

2. Communication Flow

2.1 Initial Connection

1. Client Connects to Server: The client establishes a WebSocket connection with the server at a predefined URI.

   • Example WebSocket URI: ws://<server-address>:<port>/ws/translate/<session_id>
   • wss://agents.monkeyenglish.net/ws/translate/123
     session_id: random_string

2. Task Metadata: The client sends an initial message to define the task. This message includes:

   • Source Language: The language of the audio input (e.g., eng for English).
   • Target Language: The language for translation (e.g., vie for Vietnamese).
   • Task Type: The processing task (e.g., S2TT for Speech-to-Text-to-Translation).

   Message Format (JSON):

   {
       "type": "start",
       "data": {
           "source": "eng",
           "target": "vie",
           "task": "S2TT"
       }
   }
   

2.2 Streaming Audio Data

1. Audio Streaming: The client reads and sends audio data in chunks to the server. Each chunk is a segment of the full audio file, mimicking real-time audio streaming.

   • The audio data is converted into a byte stream for transmission.

2. Transmission Format:

   • Audio chunks are transmitted in binary format (e.g., byte array).
   • Each chunk is sent over the WebSocket connection, followed by a short delay to simulate real-time audio capture.

3. Streaming Example:

   • For every audio chunk, the client sends the binary data over the established WebSocket connection.
   • The client continues sending chunks until the entire audio file has been transmitted.

2.3 Task Completion

1. End of Transmission: After the client finishes sending all audio chunks, it sends a final message to the server indicating that the streaming is complete and the task can be processed.

   Message Format (JSON):

   {
       "type": "do_task",
       "data": {
           "source": "eng",
           "target": "vie",
           "task": "S2TT"
       }
   }
   

2. Processing Response: The server processes the received audio, performing the requested task (e.g., transcription and translation). Once complete, the server responds with the result, which may include:

   • Transcribed text.
   • Translated text.

3. Response Format: The server sends a JSON message back to the client containing the task's result:

{
"message": "",
"data": {
"vie": {
"text": "thế là sáng hôm sau cái tin tôi về đến cổng còn phải thăm đường đã lan ra khóc sóng",
"audio": "https://vnmedia2.monkeyuni.net/App/uploads/productivity/8tihbdQvbQPHkcqmDntW.wav"
},
"eng": {
"text": "So the next morning, when I got back to the cage, I had to walk down the street to cry.",
"audio": "https://vnmedia2.monkeyuni.net/App/uploads/productivity/5Um6tQ1nzT3BfEqOYzx4.wav"
}
},
"status": "success"
}```

3. Client Implementation Guidelines

3.1 Supported Languages

The client can be developed in any language that supports WebSocket communication, such as:

• JavaScript: Web-based applications.
• Python: Server-side or command-line tools.
• Java/Kotlin: Android applications.
• Swift: iOS applications.
• C#: Desktop or .NET applications.

3.2 WebSocket Library

Ensure that the client uses a WebSocket library suitable for your chosen programming language. Common libraries include:

• JavaScript: Native WebSocket API or popular libraries like socket.io.
• Python: websockets or websocket-client.
• Java/Kotlin: OkHttp WebSocket implementation.
• Swift: Starscream library for WebSocket communication.

3.3 Audio File Handling

The client needs to handle reading audio files or capturing audio in real-time. The format of the audio must be compatible with the server’s requirements (e.g., 16kHz, mono, .wav ).

3.4 Chunking and Streaming

The client should send audio data in small chunks. For real-time applications:

• Chunk Size: Each chunk should be small enough to allow near real-time transmission, typically between 1-3 seconds of audio data per chunk.
• Delay: Introduce a small delay (e.g., 1-10 milliseconds) between sending each chunk to simulate real-time streaming.

3.5 Error Handling

The client must handle potential errors during the WebSocket communication:

• Connection Issues: Reconnect if the WebSocket connection is dropped.
• Server Responses: Handle unexpected responses or errors from the server gracefully.
• Timeouts: Implement timeouts to prevent hanging connections if no response is received from the server.

4. Server Configuration

4.1 Server URI

Clients must connect to the WebSocket server at the following URI:

ws://<server-address>:<port>/ws/translate/<session_id>

• <server-address>: IP address or domain of the WebSocket server.
• <port>: Port on which the server is running (e.g., 5001).
• <session_id>: A unique identifier for the client session, generated for each streaming session.

4.2 Audio Processing

The server is responsible for:

• Receiving and buffering audio chunks.
• Processing the audio (speech recognition, translation).
• Sending results back to the client in the expected format.

5. Example Use Cases

5.1 Mobile Voice Translation App

A mobile app developed in Java or Swift captures the user's voice, streams the audio to the server using WebSocket, and receives the translated text, which is displayed to the user in real-time.

5.2 Web-Based Audio Translator

A JavaScript web application allows users to upload audio files. The app streams the audio to the server, processes it, and shows the translation results to the user.

5.3 Desktop Speech-to-Text Tool

A Python desktop application records audio from the microphone, streams it to the server, and displays real-time transcription and translation.

6. Conclusion

This document provides an overview of the WebSocket-based client-server system for real-time audio streaming and processing. The client can be implemented in any language with WebSocket support, allowing flexible integration across various platforms and applications.