Skip to content
Nappai Documentation

Piper TTS

Piper TTS is a simple tool that turns written text into an audio file. It uses the open‑source Piper text‑to‑speech engine to generate high‑quality speech in a variety of languages. You can use it to create audio versions of documents, notifications, or any other text content directly from your Nappai dashboard.

How it Works

When you provide the text you want spoken, Piper TTS runs the Piper engine locally on the server. It selects the language you choose, feeds the text into the model, and outputs a binary audio file (usually in WAV or MP3 format). Because everything happens on the same machine, there are no external API calls, so the process is fast and keeps your data private.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

  • Language: Choose the language that the text will be spoken in.
  • Mapping Mode: Enable mapping mode to process multiple data records in batch.
  • Text to Speech: Enter or provide the text that you want to convert into audio.
  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
  • Tools arguments metadata: Defines the arguments metadata for the tools.

Outputs

  • Data: Binary (method: get_data). This is the generated audio file that can be saved, played, or sent to another component.
  • Tool: Tool (method: to_toolkit). This output represents the component as a tool that can be used by an AI agent.

Usage Example

  1. Set the Language to English (US).
  2. Enter the Text to Speech field with the sentence: “Welcome to Nappai. Your report is ready.”
  3. If you want to process many reports at once, toggle Mapping Mode on and connect a list of report texts to the Text to Speech input.
  4. Provide a Tool Name like “Report Audio Generator” and a helpful Tool Description such as “Converts report text into an audio file for accessibility.”
  5. Click Run.
  6. The Data output will contain the audio file, which you can then route to a File Storage component or play directly in the dashboard.
  • File Storage – Save the generated audio file to a cloud bucket or local drive.
  • Audio Player – Play the audio file directly within the dashboard.
  • Text Analyzer – Pre‑process text (e.g., summarise or translate) before sending it to Piper TTS.
  • Speech Recognition – Convert spoken audio back into text for a full text‑to‑speech‑to‑text workflow.

Tips and Best Practices

  • Keep the input text concise; very long passages may take longer to process.
  • Use the Mapping Mode when you have a list of texts to convert in one batch.
  • Choose the correct language to avoid pronunciation errors.
  • If you plan to expose the audio to external users, consider compressing the file to reduce size.
  • Test the output with a short sample before running large batches.

Security Considerations

  • All processing happens locally; no external API calls are made, so your text stays on the server.
  • The generated audio file is stored as a binary blob; ensure proper file‑system permissions to prevent unauthorized access.
  • If you expose the audio via a public URL, use secure tokens or signed URLs to control access.
  • Regularly update the Piper model directory to benefit from security patches and improvements.