========================
HARK音響ライブラリの概要
========================

概要
======

HARK音響ライブラリは、「ロボット聴覚ソフトウエア HARK」をライブラリ化し、ユーザが自ら構築するプログラムからその機能を利用できることを目指して開発されたパッケージである。

HARK では、「ノード」と呼ばれる機能単位をグラフィカルなインタフェースを用いてユーザが自由に組み合わせることで、音源定位、音源分離などの処理を簡便に実現可能であり、
また、様々な機能のノードが多数実装されていて、それらを用いて実現できる機能は多岐にわたる。
HARK は、2010年のリリース以降継続してアップデートが重ねられており、2021年時点でバージョン 3.2 が公開されている。また、これまでも多くの研究発表・アプリケーションへの適用がなされてきた。

しかし一方で、HARK はそれ自体が独立したプロセスとして動作することとなり、
ユーザが作成したプログラムと組み合わせて動作させるためには、プロセス間通信などの煩雑な処理を別途記述する必要があった。

そこで、HARK音響ライブラリでは、HARK の機能を、ユーザからはライブラリのように扱える形に再構築し、利便性を向上させることを目的として開発された。

構成
======

HARK音響ライブラリは、大きく分けて以下の5つの構成からなる。

ノード部
^^^^^^^^^^

音声区間検出、FFT、などの個々の基本的な機能を実装するのがノード部である。
それぞれの機能を実装したノード定義が提供されており、ユーザはそれらを組み合わせて利用することができる。

ノードはそれぞれが「入力」と「出力」を持ち、ノードごとにその機能に応じて入力を処理した上でその結果を出力する。

ネットワーク部
^^^^^^^^^^^^^^^^

ノードを組み合わせてより複雑な一つの機能を実現したものがネットワークである。
ネットワークは外部インタフェース的にはノードと共通化されており、ネットワークをさらに組み合わせてより複雑な機能とすることも可能である。

ミドルウェア部
^^^^^^^^^^^^^^^

ノード部・ネットワーク部は、それぞれが実際の処理を実現するものであるが、
いざ処理を実行する際には、入力されたデータを順次ノード・ネットワークに渡し、処理結果を次のノード・ネットワークに渡すなどの制御が必要である。

こういった制御を行うのがミドルウェア部である。
ミドルウェア部までの層はすべてのプラットフォームで共通である。ラッパー部より上の層では、プラットフォームごとに固有の仕様となる。

ラッパー部
^^^^^^^^^^^^

上記、ノード・ネットワーク・ミドルウェアは、C++ によって記述されている。
そのため、Python などの他言語環境からこの機能を利用するには、適宜ラッパーが必要である。

ラッパー部では、Python, C#, Swift でHARK音響ライブラリの機能を利用できるよう、実装されている。
（ただし、C++ 版の全ての機能が提供されているわけではない）

サンプルアプリ部
^^^^^^^^^^^^^^^^^

ユーザが作成するアプリケーションのサンプル。詳細は :ref:`プラットフォーム別ビルド操作について` を参照。

全体構成図
^^^^^^^^^^^^

上記をまとめて階層図に表したものを以下に示す。
図中のC# 向けサンプルアプリはWindows向けのことである。

.. image:: 構成図.png
    :width: 640px

HARK音響ライブラリのユースケース
==================================

前項の構成に基づき、ユーザがHARK音響ライブラリを利用するには、以下のようなケースが考えられる。

* 言語（Python, C#, Swift）に特化したラッパー部を利用することで、各プラットフォームから簡易な呼び出しで利用する
* C++ で記述されたミドルウェア部を利用することで、ユーザはプラットフォームへの依存を最低限にしたアプリケーションを構築する
* ノード部の機能を直接呼び出すことで、ノードとして実装されている基本的な信号処理機能を利用する

動作の仕組み
==============

前項で説明した構成を踏まえ、HARK音響ライブラリにおける動作の仕組みについて説明する。

ノードとネットワークの関係
^^^^^^^^^^^^^^^^^^^^^^^^^^^

既に述べた通り、ノードは各種の処理を行う単位として定義されており、それぞれが独立して動作する。
ネットワークは、概念上はノードの集合体として扱われるが、処理の上では各ノードに分解された上で処理されるため、ネットワークを意識した処理が行われることはほぼない。

ノードの非同期動作
^^^^^^^^^^^^^^^^^^^

ノードは、その上流からデータを取得し、必要な処理を行った上で、その結果を下流に送る。この処理は、それぞれのノードにおいて独立して非同期的に行われる。
非同期的な動作の連携のため、ノード間にはキューが設けられており、上流のノードから来たデータは一旦キューに収められた上で、順次下流のノードへ送られる。

ノードは、一定の条件を満たした場合にはその処理を行い、条件を満たさない場合は、条件が満たされるまで待機状態に入る。
条件とは、具体的には以下の２つである：

* 処理に必要な入力がそろっている。すなわち、ノードの上流にあるキューに必要なデータが全て収められている。
* 処理結果を出力することができる。すなわち、ノードの下流にあたるキューが一杯になっていない。

このような「動作条件の検証」「処理の実行とデータ送信」を繰り返すことで、HARK音響ライブラリは動作する。
全てのノードにおいて、処理開始条件を満たさず待機状態に入ったことをもって、HARK音響ライブラリは処理を終了する。

HARK音響ライブラリとユーザプログラムとの連携
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

HARK音響ライブラリをミドルウェア部も含めて用いる場合、ユーザプログラムに可能な操作は、
ネットワークを構築することと、HARK音響ライブラリの動作開始・終了を制御することに限られる。

しかしその場合、HARK音響ライブラリとユーザプログラムとの間でプログラム上でのデータの連携を行うことができない。
そこで、HARK音響ライブラリでは、ユーザプログラムとデータの送受を行う機能を持ったノードを定義している。

具体的には、以下の通りである：

* ノード PublishData：ユーザプログラムからHARK音響ライブラリへデータを渡すことができる。
* ノード SubscribeData：ユーザプログラムは、HARK音響ライブラリからデータを受け取ることができる。

なお、ノードを定義する方法については、:ref:`ノード定義の方法` を参照。

参考として、サンプルアプリケーションがHARK音響ライブラリを呼び出す際のブロック図を以下に示す。
また、ライブラリ内の処理単位 "VAD", "特徴量抽出", "正規化" はラッパー部を経由して呼び出している。

.. image:: ブロック図.png
    :width: 640px


プラットフォーム別ビルド操作について
=======================================

HARK音響ライブラリを用いたアプリケーション構築等を行うにあたって必要な操作はプラットフォームごとに異なる。

以下に必要な操作と参照先を整理する。

* Windows

  * アプリケーションの構築

    * HARK音響ライブラリを参照する C# アプリケーションを構築（:ref:`Windows 版アプリケーションの構築`）
  
  * HARK音響ライブラリの構築

    * ソースからHARK音響ライブラリを構築する（HARK音響ライブラリ開発チーム向け）（:ref:`Windows 版をソースからビルドする`）

* iOS

  * アプリケーションの構築

    * iOS アプリケーションを構築（:ref:`iOS 版アプリケーションの構築`）

  * HARK音響ライブラリの構築
  
    * 現在、上記 iOS アプリケーションと同時にビルドする形となっている

* Python

  * アプリケーションの構築

    * 本ドキュメントでは言及していない
  
  * HARK音響ライブラリの構築

    * ソースからHARK音響ライブラリを構築する（:ref:`Python 版ビルド環境の構築`）

