設計ドキュメント (Japanese)
======================================

.. note::
    Design issue tracker https://github.com/r9y9/nnmnkwii/issues/8

The underlying design philosophy
--------------------------------

- Getting better experience on rich REPL (i.e, IPython, Jupyter) boosts research productivity.

Background
----------

-  統計的音声合成は、テキスト分析、音声分析/合成、機械学習等、いくつもの要素技術からなる複合技術であり、論文の追試（結果の再現）、新しいアイデアをプロトタイピングするといった行為は、大きな労力を要する。後の研究の生産性の向上のために、音声合成における要素技術を、再利用しやすい形で提供することには価値があると考える。
-  HMM音声合成では、 HTS_ が広く使われている。HTKにパッチを適用することで使用する。HMMベースの音響モデルを構築するための仕組みがコマンドラインツール群として提供されており、それらを組みわせて柔軟にシステムが作れるように設計されている。しかし、HMMベースの音声合成に着目して設計されているため、近年の主流であるDNN音声合成には基本的には対応していない [1]_
-  Merlin_ は、DNNベースの音声合成システムを作るためのツールキットである。近年のDNNベースの音声合成システムの成功を受けて、HTSに代わるDNNベースのstate-of-the-artなシステムを再現可能な形で提供するために作られている。Merlinの主なエントリーポイントは、run_merlin.pyというコマンドラインスクリプトであり、ユーザは設定ファイルを切り替えることで、どのような音響モデルを使用するかなどを切り替える。しかし、run_merlin.pyがすべてのインタフェースとなっており、構成要素を再利用するといったことが難しい。また、音響モデルを設定ファイルで切り替えるという設計がゆえに、Merlinのソースコードを改変せずに音響モデルを自在に変えることも難しい。同様に、Theano or kerasに依存した構造になっているため、他のDeep learningフレームワークとは、ソースコードを改変せずには使用できず、柔軟性に欠けていると言える。

.. _HTS: http://hts.sp.nitech.ac.jp/
.. _Merlin: https://github.com/CSTR-Edinburgh/merlin

このような背景から、近年のDNNベースの音声合成の研究に役に立つ、ユーザが自由に構成要素を利用できる（i.e., 言語特徴量の計算だけ、パラメータ生成だけ、ポストフィルタだけ等）、ユーザが好きな自動微分ライブラリを使える（PyTorch, etc）、Modularで柔軟なライブラリがほしいと思いました。

Goal
----

対話環境での試行錯誤が研究の生産性の向上に重要であると信じ、対話環境での利用を前提とした、音声合成、声質変換のためのライブラリを構築する。主なゴールは、

- Easy and fast prototyping

が可能であることとする。コードはMITライセンスで公開し、研究の再現性の保証にも役立つことも狙う。

So what do we provide?
----------------------

HMM音声合成からのDNN音声合成の発展、End-to-end音声合成 (e.g., Char2Wav_) 、ボコーダレスの音声合成の発展(e.g., WaveNet_)など、音声合成の枠組みは多岐に渡る。すべてを網羅する機能を提供することは困難であり、ライブラリを複雑かつメンテナンスを難しいものにしてしまう。したがって、提供する機能を（少なくとも最初は）最も汎用的な部分に留めることが重要であると考える。
また、扱うデータ量は大きくなっており、大規模データも視野に入れる必要がある。

.. _Char2Wav: http://www.josesotelo.com/speechsynthesis/
.. _WaveNet: https://deepmind.com/blog/wavenet-generative-model-raw-audio/

DNNを用いた機械学習においては、tensorflow, keras, cntk, pytorch, theano,
caffe, mxnet,
chainer等に代表されるように、CUDAを活用した多次元配列上の数値演算、自動微分をサポートしたフレームワークが必須になってきている。音声、画像、言語など、データを多次元配列として表現できる場合は多くあり、ドメインを問わず多くの分野で使われている。
本ライブラリは、そういった汎用的な自動微分フレームワークと併せて使用されることを想定し、

-  大規模データを想定したデータセットの構築、データアクセスの抽象化 :obj:`nnmnkwii.datasets`
-  音声に特化した汎用的な関数 :obj:`nnmnkwii.autograd`
-  パラメータ生成、前処理/後処理アルゴリズム :obj:`nnmnkwii.preprocessing`, :obj:`nnmnkwii.paramgen`, :obj:`nnmnkwii.postfilters`

に注目し、機能を提供すればよいと考える。

Design decisions
----------------

ソフトウェアの設計方針として、以下が挙げられる。

1. 対話環境で使えるPythonパッケージとして提供する。コマンドラインツールは、必要であればユーザが作ればよいと考え、本ライブラリでは提供しないこととする。
2. 対話環境での使用を前提とするため、基本的にIOはin-memoryととる
3. 音響モデルの提供は、ライブラリの範囲外とする。もっともユーザが自分で考えて設定したい部分と考えられるためである。Merlinとは異なり、音響モデルを提供するのではなく、音響モデルを構築するための要素を提供する。
4. 言語特徴量の抽出 (i.e. frontend)
   は、基本的にHTSやMerlinと同様にライブラリの範囲外とする。
5. 音響特徴量の抽出は、ライブラリの範囲外とする。 ``pysptk``,
   ``pyworld``, ``librosa`` など別パッケージを使用すればよい。

HTSのデモスクリプトのように、音声合成システム全体が複雑になってしまうのは、避けられない問題であると考える。本ライブラリでは、構成要素がシンプルで小さく、要素同士が疎結合であることを目指し、理解しやすい、再利用しやすいソフトウェアを目指す。

Development guidelines
----------------------

開発においては、以下を指針とする

-  **Do not reinvent the wheel**: 車輪の再発明は可能な限り避ける
-  **Fully unit tested**:
   バグのないソフトウェアはない。テストによって、可能な限りバグを少なくする、再発を避ける。
-  **Documentation**: ドキュメントを書くのは大変だが、大事である

.. [1]
   DNN音声合成を行うデモスクリプトは存在するが、あくまでデモスクリプトであり、ライブラリとしての機能にあるわけではない。