💠 aivmlib: Aivis Voice Model File (.aivm) Utility Library
AIVM (Aivis Voice Model) は、学習済みモデル・ハイパーパラメータ・スタイルベクトル・話者メタデータ（名前 / 概要 / アイコン / ボイスサンプル など）を 1 つのファイルにギュッとまとめた、AI 音声合成モデル用オープンファイルフォーマットです。
AivisSpeech / AivisSpeech-Engine をはじめとした対応ソフトウェアに AIVM ファイルを追加することで、AI 音声合成モデルを簡単に利用できます。
このライブラリでは、AIVM ファイルのメタデータを読み書きするためのユーティリティを提供します。
Tip
AIVM Generator では、ブラウザ上の GUI で AIVM ファイルを生成・編集できます。
機能的には aivmlib と同じです。手動で AIVM ファイルを生成・編集する際は AIVM Generator の利用をおすすめします。
以下に CLI ツール自体の使い方を示します。
$ python -m aivmlib --help
Usage: python -m aivmlib [OPTIONS] COMMAND [ARGS]...
Aivis Voice Model File (.aivm) Utility Library
╭─ Options ─────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it │
│ or customize the installation. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────╮
│ create-aivm 与えられたアーキテクチャ, 学習済みモデル, ハイパーパラメータ, │
│ スタイルベクトルから AIVM メタデータを生成した上で、 │
│ それを書き込んだ仮の AIVM ファイルを生成する │
│ show-metadata 指定されたパスの AIVM ファイル内に記録されている AIVM │
│ メタデータを見やすく出力する │
╰───────────────────────────────────────────────────────────────────────────────────╯
$ python -m aivmlib create-aivm --help
Usage: python -m aivmlib create-aivm [OPTIONS]
与えられたアーキテクチャ, 学習済みモデル, ハイパーパラメータ, スタイルベクトルから
AIVM メタデータを生成した上で、 それを書き込んだ仮の AIVM ファイルを生成する
╭─ Options ─────────────────────────────────────────────────────────────────────────╮
│ * --output -o PATH Path to the output AIVM │
│ file │
│ [default: None] │
│ [required] │
│ * --model -m PATH Path to the Safetensors │
│ model file │
│ [default: None] │
│ [required] │
│ * --hyper-parameters -h PATH Path to the hyper │
│ parameters file │
│ [default: None] │
│ [required] │
│ --style-vectors -s PATH Path to the style │
│ vectors file (optional) │
│ [default: None] │
│ --model-architecture -a [Style-Bert-VITS2|Styl Model architecture │
│ e-Bert-VITS2 [default: │
│ (JP-Extra)] Style-Bert-VITS2 │
│ (JP-Extra)] │
│ --help Show this message and │
│ exit. │
╰───────────────────────────────────────────────────────────────────────────────────╯
$ python -m aivmlib show-metadata --help
Usage: python -m aivmlib show-metadata [OPTIONS] AIVM_FILE_PATH
指定されたパスの AIVM ファイル内に記録されている AIVM メタデータを見やすく出力する
╭─ Arguments ───────────────────────────────────────────────────────────────────────╮
│ * aivm_file_path PATH Path to the AIVM file [default: None] [required] │
╰───────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────╯Tip
ライブラリとしての使い方は、__main__.py に実装されている CLI ツールの実装を参照してください。
Important
aivmlib は、AIVM ファイルフォーマットの読み込み/書き込み機能のみを有するライブラリです。
各モデルアーキテクチャごとの音声合成モデルの推論ロジックや、aivmlib から取得したデータをどのようにユーザーに提示するかは、すべてライブラリの利用者に委ねられています。
以下に AIVM ファイルフォーマットの仕様を示す。
AIVM (Aivis Voice Model) は、Safetensors (.safetensors) 形式で保存された学習済み音声合成モデルのヘッダー領域の中に、カスタムメタデータとして話者メタデータ (AIVM マニフェスト) ・ハイパーパラメータ・スタイルベクトルといった各種情報を格納した、Safetensors 形式の拡張仕様である。
言い換えるならば、「音声合成モデル向けの、Safetensors 形式の共通メタデータ記述仕様」でもある。
学習済み音声合成モデルと、その利用に必要な各種メタデータを単一ファイルにまとめることで、ファイルの散逸や混乱を防ぎ、モデルの利用や共有を容易にすることを目的としている。
AIVM 仕様は、音声合成モデルのモデルアーキテクチャに依存しない。
異なるモデルアーキテクチャの音声合成モデルを共通のファイルフォーマットで扱えるよう、拡張性や汎用性を考慮して設計されている。
大元の学習済み音声合成モデルが Safetensors 形式で保存されているならば、原則どのようなモデルアーキテクチャであっても、メタデータを追加して AIVM ファイルを生成できる。
Important
AIVM 仕様は、各モデルアーキテクチャごとの推論方法を定義しない。あくまでも「音声合成モデルのメタデータをまとめたファイル」としての仕様のみを定義する。
たとえば格納されている音声合成モデルは PyTorch 用かもしれないし、TensorFlow 用かもしれない。
音声合成モデルをどのように推論するかは、AIVM ファイルをサポートするソフトウェアの実装に委ねられている。
Safetensors 形式の拡張仕様のため、そのまま通常の Safetensors ファイルとしてロードできる。
Safetensors 同様、先頭 8bytes の符号なし Little-Endian 64bit 整数がヘッダーサイズ、その後ろにヘッダーサイズの長さだけ UTF-8 の JSON 文字列が続く。
Safetensors のヘッダー JSON にはテンソルのオフセット等が格納されているが、__metadata__ キーには string から string への map を自由に設定可能な仕様である。
この仕様を活用し、AIVM は __metadata__ 内の以下のキーに次のデータを JSON 文字列にシリアライズして格納する。
aivm_manifest: AIVM マニフェスト- JSON 文字列で格納される
- マニフェストバージョンや話者メタデータを含む大半の情報が含まれる
aivm_hyper_parameters: 音声合成モデルのハイパーパラメータ- 格納フォーマットはモデルアーキテクチャ依存
Style-Bert-VITS2・Style-Bert-VITS2 (JP-Extra)モデルアーキテクチャでは JSON 文字列で格納される
aivm_style_vectors: Base64 エンコードされた音声合成モデルのスタイルベクトル (バイナリ)- Base64 デコード後のフォーマットはモデルアーキテクチャ依存
Style-Bert-VITS2・Style-Bert-VITS2 (JP-Extra)モデルアーキテクチャでは NumPy 配列 (.npy) を Base64 エンコードした文字列で格納される- モデルアーキテクチャ次第では省略されうる
以下に AIVM ファイルフォーマットに含まれる、AIVM マニフェスト (Version 1.0) の仕様を示す。
AIVM マニフェストは、JSON フォーマットで記述された UTF-8 文字列である。
AIVM マニフェストには、マニフェストバージョン (= AIVM ファイルバージョン)・モデルアーキテクチャ・モデル名・話者メタデータ・スタイル情報などの、音声合成モデルの利用に必要となる様々な情報が含まれる。
JSON フォーマットの都合上、画像や音声データは Base64 エンコードされた文字列で格納される。
Style-Bert-VITS2Style-Bert-VITS2 (JP-Extra)
Important
AIVM ファイルをサポートするソフトウェアでは、自ソフトウェアではサポート対象外のモデルアーキテクチャの AIVM ファイルを、適切にバリデーションする必要があります。
たとえば Style-Bert-VITS2 (JP-Extra) 以外のモデルアーキテクチャをサポートしないソフトウェアでは、Style-Bert-VITS2 モデルアーキテクチャの AIVM ファイルのインストールを求められた際に「このモデルアーキテクチャには対応していません」とアラートを表示し、インストールを中止すべきです。
Important
技術的には上記以外のモデルアーキテクチャの音声合成モデルも格納できますが、AIVM マニフェスト (Version 1.0) 仕様で公式に定義されているモデルアーキテクチャ文字列は上記のみです。
独自にモデルアーキテクチャ文字列を定義する場合は、既存のモデルアーキテクチャとの名前衝突や異なるソフト間での表記揺れが発生しないよう、細心の注意を払う必要があります。
なるべくこのリポジトリにプルリクエストを送信し、公式に AIVM 仕様に新しいモデルアーキテクチャのサポートを追加する形を取ることを推奨します。
以下は AIVM マニフェスト (Version 1.0) 仕様時点での AIVM マニフェストのフィールド定義を示す (Pydantic スキーマ定義 より抜粋) 。
Important
AIVM マニフェスト内のフィールドは、今後 AIVM 仕様が更新された際に追加・拡張・削除される可能性がある。
今後のバージョン更新や追加のモデルアーキテクチャのサポートにより、AIVM マニフェストや AIVM ファイルフォーマット自体に新しいメタデータが追加されることも十分考えられる。
現在有効な AIVM マニフェストバージョンは 1.0 のみ。
class ModelArchitecture(StrEnum):
StyleBertVITS2 = 'Style-Bert-VITS2'
StyleBertVITS2JPExtra = 'Style-Bert-VITS2 (JP-Extra)'
class AivmManifest(BaseModel):
""" AIVM マニフェストのスキーマ """
# AIVM マニフェストのバージョン (ex: 1.0)
# 現在は 1.0 のみサポート
manifest_version: Annotated[str, constr(pattern=r'^1\.0$')]
# 音声合成モデルの名前
name: Annotated[str, constr(min_length=1)]
# 音声合成モデルの説明 (省略時は空文字列になる)
description: str = ''
# 音声合成モデルの利用規約 (Markdown 形式 / 省略時は空文字列になる)
terms_of_use: str = ''
# 音声合成モデルのアーキテクチャ (音声合成技術の種類)
model_architecture: ModelArchitecture
# 音声合成モデルを一意に識別する UUID
uuid: UUID
# 音声合成モデルのバージョン (SemVer 2.0 準拠 / ex: 1.0.0)
version: Annotated[str, constr(pattern=r'^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$')]
# 音声合成モデルの話者情報 (最低 1 人以上の話者が必要)
speakers: list[AivmManifestSpeaker]
class AivmManifestSpeaker(BaseModel):
""" AIVM マニフェストの話者情報 """
# 話者の名前
name: Annotated[str, constr(min_length=1)]
# 話者の対応言語のリスト (ja, en, zh のような ISO 639-1 言語コード)
supported_languages: list[Annotated[str, constr(min_length=2, max_length=2)]]
# 話者を一意に識別する UUID
uuid: UUID
# 話者のローカル ID (この音声合成モデル内で話者を識別するための一意なローカル ID で、uuid とは異なる)
local_id: int = Field(ge=0)
# 話者のバージョン (SemVer 2.0 準拠 / ex: 1.0.0)
version: Annotated[str, constr(pattern=r'^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$')]
# 話者のスタイル情報 (最低 1 つ以上のスタイルが必要)
styles: list[AivmManifestSpeakerStyle]
class AivmManifestSpeakerStyle(BaseModel):
""" AIVM マニフェストの話者スタイル情報 """
# スタイルの名前
name: Annotated[str, constr(min_length=1)]
# スタイルのアイコン画像 (Data URL)
# 最初のスタイルのアイコン画像が話者単体のアイコン画像として使用される
icon: str
# スタイルのボイスサンプル (省略時は空配列になる)
voice_samples: list[AivmManifestVoiceSample]
# スタイルの ID (この話者内でスタイルを識別するための一意なローカル ID で、uuid とは異なる)
local_id: int = Field(ge=0, le=31)
class AivmManifestVoiceSample(BaseModel):
""" AIVM マニフェストのボイスサンプル情報 """
# ボイスサンプルの音声ファイル (Data URL)
audio: str
# ボイスサンプルの書き起こし文
transcript: str