I Built a VOICEVOX Intermediate API Server: Easily Integrate VOICEVOX with Your Own Apps

Hello, this is Rcat.
Last time, I introduced how to use the Linux version of VOICEVOX from the shell via SSH.
As an extension of that, this time I'm going to set up a VOICEVOX speech synthesis server on Linux.
This will make it easier to access the API and use it from various custom applications.

Introduction

Terms of Service

Please check the terms of service in advance when using information or works.

About Comments

Please check the terms of service guidelines before commenting.

Overview

Background

A while ago, I created a fully automated voice dubbing tool in this article.
As I explained briefly there, the VOICEVOX core API requires complex content to be sent, and you need to build a dedicated program to use it.
At the time, I created a Python module, so if you are using Python, you can just import it, but for other languages or if you are copying custom modules to various places, management can become cumbersome.
In that case... I should just build an easy-to-use Web API.

What do you mean by an intermediate server?

As I mentioned above, the point is that while there is a Web API originally, it is difficult to use, so I am creating an API that is easier to use instead.

To give you an idea of how difficult it is, it looks like this.

At first, you only need to pass who is reading and the text to be read, but for the second one, you are required to provide a huge amount of parameters.
Well, almost all of these parameters are content returned from the first API, but in the end, you need a program to bridge these APIs.

So, here is a diagram of the system I thought of this time.

The client only hits one API on the intermediate server.
Then, the intermediate server hits the two official APIs to generate audio.
Also, the intermediate server accepts requests via GET parameters, making it easier to use.
Furthermore, VOICEVOX output is in wav, but by using FFMPEG within the intermediate server to convert it to MP3 or ogg, it can also return data with a reduced size.

Features and Usage

Use Cases

Basically, it is used to be called from other programs, and I do not assume it will be used by connecting directly to a Web server.

For example, Dify, in the case of using reading out text generated using AI via an http request within a workflow is something that can be assumed.
I haven't confirmed if it can handle audio data, though...
For things like this where you can make some adjustments yourself but cannot go deep into the system, it is very convenient to have such a Web API prepared.

Other use cases include when you want to build a smartphone app and add a reading function, allowing you to perform reading via a network.

Installing Python

This project is built with Python.
Therefore, you first need to install Python.
Please refer to the following article for instructions on how to install it.

Additionally, if you use features that require FFMPEG, you must install FFMPEG and configure the PATH.

Features

This server includes the following features

• Text-to-speech functionality using VOICEVOX

  • Read arbitrary text aloud
    You can have the input text read aloud.

  • Arbitrary character selection
    You can select a character by specifying their ID.

  • Speech speed adjustment
    You can select the speech speed from either of the following.

    • Speed setting function

    • Duration setting function
      You can specify the time it takes to read aloud in seconds. Strictly speaking, it adjusts the speed to match that number of seconds. It will never be an exact match, so there is some margin of error.

  • Conversion to compressed file formats (FFMPEG required)

    • MP3

    • OGG

  • Executable via GET or POST
    You can execute it with a simple GET, or use POST for longer text.

• VOICEVOX Character ID Search Function
  A feature that displays the official API's ID information in an easy-to-read format.

• VOICEVOX Startup Function
  A feature to execute the startup script on the computer where the server is running.
  It is executed automatically when the program starts, and can also be executed by hitting a specific URL.

• Test Read-Aloud Execution
  You can perform a test of the cgi.

Top Page

When you access this server, a screen like the one below will appear.
On this screen, you can use the cgi explanation and the character ID search function.

Character ID Search Function

By selecting from the dropdown box under "Look up character ID" on the top page, you can check the ID and style of each character.

By selecting a character, a table of IDs and styles will be displayed below it.

Server Status Display

You can check the status of the two pieces of software this project depends on.
VOICEVOX must be running to perform read-alouds.
When outputting, FFMPEG must be available if you want to specify a format other than wav.

* Depending on the FFMPEG installation status, it may not be possible to convert even if it says available because dependent libraries are missing, so please try manually beforehand to see if you can convert to mp3 and ogg. The version included by default in Ubuntu could not perform the conversion.

How to use the read-aloud function

The usage of the read-aloud API is as follows.

サーバーアドレス/talk?text=読み上げたいテキスト

The absolutely required argument is text.
Everything else is optional, and by default, it will read aloud using Shikoku Metan.

To specify additional parameters, do it as follows.

サーバーアドレス/talk?text=読み上げたいテキスト&cid=キャラID&format=mp3/ogg&length=長さ

Parameters can be combined with the & symbol.
For example, in the following example, it reads aloud using Kasukabe Tsumugi, the output format is MP3, and the speed is adjusted so that the file length is 2 seconds.
Please note that you can only use either speed adjustment or length adjustment, not both.

In this example, the format is set to ogg and the instruction is to read at 1.5x speed.

How to access from Python

The method for accessing the API and saving audio using Python is as follows.

R:\tmp>py
Python 3.11.6 (tags/v3.11.6:8b6ee5b, Oct  2 2023, 14:57:12) [MSC v.1935 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> r = requests.get("http://localhost:25607/talk?text=ねこきゃっとにゃん&cid=3")
>>> f = open("vv.wav","wb")
>>> f.write(r.content)
53804
>>> f.close()

Since this API returns the audio binary directly, you should write the response content to a file or byte IO to use it.
In this case, since it is being saved to a file, you can verify whether it was generated correctly by trying to play it back.

When executing with POST

Next, I will introduce how to make a request using POST.
The keywords required for the request are the same as for GET. The URL is also the same.
In the case of POST, you perform the text-to-speech by formatting the request body as JSON and including the parameters within it.
When using Python, the easiest way is to put the parameters into a dictionary and POST them using requests.

R:\tmp>py
Python 3.11.6 (tags/v3.11.6:8b6ee5b, Oct  2 2023, 14:57:12) [MSC v.1935 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> data = {
... "text":"ねこきゃっとにゃん",
... "cid":14, #冥鳴ひまり
... "format":"ogg"
... }
>>> r = requests.post("http://localhost:25607/talk",json=data)
>>> f = open("vv2.ogg","wb")
>>> f.write
f.write(      f.writelines(
>>> f.write(r.content)
10516
>>> f.close()

How to use the VOICEVOX startup feature

You probably won't worry about this much on Windows, but if you are using a Linux server, you cannot have it start automatically unless you add VOICEVOX to systemd.
However, it's a hassle to keep two programs running, isn't it?
So, I have included a feature in this program to launch VOICEVOX.

Preparing a startup script

Since whether it starts with a single command or not varies depending on the environment, I have made it possible to launch it universally by preparing a dedicated script.
I have included samples for both Windows and Linux, so please rewrite them as a reference.

Please execute this script manually in advance to confirm that VOICEVOX launches.

If the official API cannot be accessed when this server starts, it will automatically launch VOICEVOX.

Accessing the startup API

Basically, it should launch automatically at startup, so you shouldn't need to use this, but if it becomes necessary, you can execute the startup script by accessing the following URL.

/vvstart?key=起動キー

The startup key is defined at the very top of the program.
Please rewrite it to your preferred key before using it.
Although it is intended for my own use, there might be cases where it isn't, so I have added a safety measure called a startup key. I haven't implemented things like login, as it's not really necessary for this level of usage.

This is what it looks like when you actually access it.
At this time, it was already running, so an error message was displayed.

Summary

How was it?
This time, I created an intermediate server to utilize VOICEVOX more flexibly in various applications.
I personally think that combinations with text-generating AI are particularly promising.
Since I only made the intermediate server this time, it might feel like 'so what?', but I would like to build on this in the future.
See you next time.

Distribution Information

Distribution URL

It is distributed from the following URL.
Terms of ServicePlease agree to the before using.

https://script.google.com/macros/s/AKfycbxdcr8pnazR7RbjaSICTtaNWfN7h_rjQrKlZ3h9CZpPRFzRILk1OGc8mZqKbF-NXNO9/exec?name=VOICEVOX_Intermediate_API_Server

Dependent Modules

The voicevox.py file included in the tool introduced below is required separately.