Package com.tnsai.tools.media

Class MediaTools

java.lang.Object

com.tnsai.tools.media.MediaTools

public class MediaTools
extends Object

Function-shape OpenAI media tools — speech-to-text (Whisper) + text-to-speech. Replaces the legacy WhisperTool, AudioTranscriptionTool (a duplicate of Whisper hitting the same endpoint), and TextToSpeechTool.

Method	Endpoint	Idempotent
whisperTranscribe(java.lang.String, java.lang.String)	POST /v1/audio/transcriptions	true
openaiTts(java.lang.String, java.lang.String, java.lang.String)	POST /v1/audio/speech	true

Both require OPENAI_API_KEY. The legacy ChatterboxTTSTool + ChatterboxStreamingTool (third-party TTS vendor, 800+ combined lines) are intentionally deferred — they need their own dedicated batch.

Since:

0.5.7 (Phase 2 batch 23 — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
MediaTools()	Default constructor — picks OPENAI_API_KEY from env.
MediaTools(String apiKey)	Explicit-key constructor.
MediaTools(String apiKey, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor for tests / shared HTTP.

Method Summary

Modifier and Type	Method	Description
String	openaiTts(String text, String voice, String format)
String	whisperTranscribe(String audioPath, String language)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MediaTools

public MediaTools()

Default constructor — picks OPENAI_API_KEY from env.

MediaTools

public MediaTools(String apiKey)

Explicit-key constructor.

MediaTools

public MediaTools(String apiKey,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor for tests / shared HTTP.

Method Details

whisperTranscribe

@Tool(name="whisper_transcribe",
      description="Transcribe an audio file to text using OpenAI Whisper ({audioPath} accepts MP3 / WAV / M4A / WEBM / OGG, max 25 MB). Optional {language} narrows recognition to a single ISO-639 code (e.g. \"en\", \"tr\", \"de\") \u2014 blank = auto-detect. Returns the raw JSON Whisper response. Requires OPENAI_API_KEY.",
      keywords={"whisper","stt","speech","transcribe","audio","openai"},
      idempotent=true)
public String whisperTranscribe(@ToolParam(description="Absolute path to the audio file (max 25 MB)")
 String audioPath,
 @ToolParam(description="Optional ISO-639 language code; blank = auto-detect",required=false,defaultValue="")
 String language)
                         throws IOException

Throws:

IOException

openaiTts

@Tool(name="openai_tts",
      description="Synthesize speech from {text} via OpenAI TTS. {voice} is one of \"alloy\" (default), \"echo\", \"fable\", \"onyx\", \"nova\", \"shimmer\". {format} is \"mp3\" (default), \"wav\", \"opus\", \"aac\", or \"flac\". Returns base64-encoded audio bytes. Max text length 4096 characters. Requires OPENAI_API_KEY.",
      keywords={"tts","speech","audio","voice","speak","openai","synthesis"},
      idempotent=true)
public String openaiTts(@ToolParam(description="Text to synthesize (max 4096 chars)")
 String text,
 @ToolParam(description="Voice: alloy / echo / fable / onyx / nova / shimmer",required=false,defaultValue="alloy")
 String voice,
 @ToolParam(description="Output format: mp3 / wav / opus / aac / flac",required=false,defaultValue="mp3")
 String format)
                 throws IOException

Throws:

IOException