Merge pull request #36 from AutumnSky1010/prepare/#35

Write the documents

docs/HowToUseDocFX.md

@@ -0,0 +1,7 @@
+# ローカル環境でドキュメントをプレビューする方法
+リポジトリルートで、
+```
+docfx docs\docfx.json --serve
+```
+
+を実行する。

docs/docfx.json

@@ -36,9 +36,12 @@
       "modern"
     ],
     "globalMetadata": {
-      "_appName": "SoundMaker API Reference",
-      "_appTitle": "SoundMaker API Reference",
+      "_appName": "SoundMaker Documentation",
+      "_appTitle": "SoundMaker Documentation",
+      "_appFooter": "SoundMaker © 2022-2024",
       "_enableSearch": true,
+      "_appLogoPath": "images/favicon.png",
+      "_appFaviconPath": "images/favicon.png",
       "pdf": false
     }
   }

docs/index.md

@@ -2,10 +2,62 @@
 _layout: landing
 ---
 
-# This is the **HOMEPAGE**.
 
-Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
+![cover](./images/SoundMakerCover.png)  
+[![Pipeline](https://github.com/AutumnSky1010/SoundMaker/actions/workflows/build.yml/badge.svg)](https://github.com/AutumnSky1010/SoundMaker/actions/workflows/build.yml)  
 
-## Quick Start Notes:
+# SoundMakerとは
+SoundMakerは、.NET上で動作する音を生成するライブラリです。
 
-1. Add images to the *images* folder if the file is referencing an image.
+## 特徴
+### 「音程がC4の四分音符」というように音楽の知識で音を生成できます
+```cs
+// 音符
+new Note(Scale.C, 5, LengthType.Eighth, isDotted: true);
+// 休符
+new Rest(LengthType.Quarter);
+// タイ
+new Tie(new Note(Scale.D, 5, LengthType.Eighth), LengthType.Eighth);
+// 連符
+new Tuplet([new Note(Scale.D, 5, LengthType.Eighth), new Note(Scale.D, 5, LengthType.Eighth)], LengthType.Quarter);
+```
+
+### 周波数を指定しても音を生成できます
+```cs
+var triangleWave = new TriangleWave();
+int hertz = 800;
+int length = (int)format.SamplingFrequency * 5;
+int volume = 50;
+short[] waveShorts = triangleWave.GenerateWave(format, length, volume, hertz);
+```
+
+### リニアPCMのWAVを出力することができます
+```cs
+var builder = FormatBuilder.Create()
+    .WithFrequency(48000)
+    .WithBitDepth(16)
+    .WithChannelCount(2);
+
+var sound = new SoundWaveChunk(/* 音声波形バイト列 */);
+var waveFileFormat = builder.ToFormatChunk();
+var writer = new WaveWriter(waveFileFormat, sound);
+string filePath = "sample.wav";
+writer.Write(filePath);
+```
+
+ストリームへ書き込むことも可能です。
+```cs
+writer.Write(stream);
+```
+
+### 楽譜記述フォーマットを提供
+簡単な楽譜記述フォーマットのシリアライズ・デシリアライズ機能を提供しています。
+```
+// コメントアウト
+// 付点四分音符(音階はC#4)
+C#4, 4.
+// 休符
+rest, 4.
+// タイ と 三連符(4分音符を三等分している)
+tie(C4, 4, 4, 4); tup(4, C4, C4, C4)
+```

docs/markdowns/introduction.md

@@ -1 +1,2 @@
-# Introduction
+# イントロダクション
+ここではSoundMakerの使用例をプログラムを示しながら紹介します。

docs/markdowns/migrate-to-ver-3.md

@@ -0,0 +1,28 @@
+# Ver 3.0.0への移行ガイド
+
+SoundMaker Ver 3.0.0への移行に関して、以下のガイドラインに従ってください。メジャーバージョンアップにより、破壊的変更が含まれていますのでご注意ください。
+
+## .NET 7以前を利用している場合は.NET 8以降へアップデートする
+.NET 6のサポート終了に伴い、SoundMakerも.NET 8へ移行しました。.NET 8へのアップデートは以下の手順で行います：
+1. **.NET SDKのインストール**: 最新の.NET 8 SDKを[公式サイト](https://dotnet.microsoft.com/download/dotnet/8.0)からダウンロードしてインストールします。
+2. **プロジェクトファイルの更新**: 各プロジェクトの`TargetFramework`を`.NET 8`に更新します。例えば、`.csproj`ファイルで以下のように変更します：
+    ```xml
+    <TargetFramework>net8.0</TargetFramework>
+    ```
+3. **依存関係の更新**: `.NET 8`に対応するライブラリやパッケージのバージョンを確認し、必要に応じてアップデートします。
+
+## ushort[]型からshort[]型を利用するように変更する
+音声波形は符号付き整数を利用することが一般的なので、Ver 3.0.0では`ushort`型から`short`型に変更しました。以下の手順で対応します：
+**コードの修正**: `ushort[]`型を使用している箇所をすべて`short[]`型に変更します。例えば、
+```csharp
+// 旧コード
+ushort[] sample = [32767];
+
+// 新コード
+short[] sample = [32767];
+```
+
+## 廃止機能を利用しない
+Ver 3.0.0以前に`Obsolete`属性がついたメソッドやプロパティは削除されました。これに対応するためには、以下の手順を行います：
+1. **コードのチェック**: `Obsolete`属性が付与されたメソッドやプロパティを使用している箇所を確認します。これらはコンパイラ警告として表示されることが多いです。
+2. **代替機能の利用**: `Obsolete`となった機能の代替となるメソッドやプロパティを使用します。削除された機能に関する詳細は、削除を行ったプルリクエストを参照してください：[削除を行ったプルリクエスト](https://github.com/AutumnSky1010/SoundMaker/pull/29/files)

docs/markdowns/smsc/serializer.md

@@ -0,0 +1,55 @@
+# SMSCシリアライズ・デシリアライズ
+
+SMSCデータをシリアライズおよびデシリアライズする方法を示します。
+
+### シリアライズ
+
+以下のコード例では、サウンドコンポーネントをSMSC形式にシリアライズする方法を示しています。
+
+#### コード例
+```cs
+// using SoundMaker.ScoreData.SMSC;
+// using SoundMaker.Sounds.Score;
+var components = new List<ISoundComponent>()
+{
+    new Note(Scale.E, 5, LengthType.Eighth),
+    new Note(Scale.F, 5, LengthType.Eighth),
+    new Note(Scale.G, 5, LengthType.Eighth),
+};
+var smsc = SMSCFormat.Serialize(components);
+Console.WriteLine(smsc);
+```
+
+#### 詳細な説明
+
+1. **サウンドコンポーネントの作成**: `ISoundComponent` を実装したクラス（例：`Note`）のオブジェクトをリストに追加します。
+    - `new Note(Scale.E, 5, LengthType.Eighth)`: 音階E、5オクターブ、長さは八分音符の音を作成。
+    - 同様に、音階FおよびGの音符も追加します。
+2. **シリアライズ**: `SMSCFormat.Serialize` メソッドを使用して、サウンドコンポーネントのリストをSMSC形式にシリアライズします。
+3. **出力**: シリアライズされたSMSCデータをコンソールに出力します。
+
+### デシリアライズ
+
+以下のコード例では、SMSC形式のデータをサウンドコンポーネントにデシリアライズする方法を示しています。
+
+#### コード例
+```cs
+// using SoundMaker.ScoreData.SMSC;
+// using SoundMaker.Sounds.Score;
+var smsc = "C4, 4";
+var result = SMSCFormat.Read(smsc);
+if (result.TryGetValue(out IReadOnlyList<ISoundComponent> components))
+{
+}
+else
+{
+}
+```
+
+#### 詳細な説明
+
+1. **SMSCデータの読み込み**: シリアライズされたSMSC形式の文字列を用意します。例：`"C4, 4"`。
+2. **デシリアライズ**: `SMSCFormat.Read` メソッドを使用して、SMSC形式のデータをサウンドコンポーネントにデシリアライズします。
+3. **結果の確認**:
+    - `result.TryGetValue(out IReadOnlyList<ISoundComponent> components)`: デシリアライズに成功した場合、サウンドコンポーネントのリストを取得します。
+    - デシリアライズに失敗した場合の処理も含めます。

docs/markdowns/smsc/what-is-the-smsc.md

@@ -0,0 +1,21 @@
+# SMSCフォーマットとは？
+## 概要
+簡単にSoundMaker用の楽譜を記述するためのフォーマットです。詳細な情報は設定できませんが、簡単に記述できます。  
+チャンネルやトラックの完全なデータを永続化する目的では利用できないことに注意してください。
+
+## 例
+```
+// コメントアウト
+// 付点四分音符(音階はC#4)
+C#4, 4.
+// 休符
+rest, 4.
+// タイ と 三連符(4分音符を三等分している)
+tie(C4, 4, 4, 4); tup(4, C4, C4, C4)
+```
+
+## 仕様
+[BNF(バッカス・ナウア記法)](https://github.com/AutumnSky1010/SoundMaker/blob/master/src/SoundMaker/ScoreData/SMSC/SMSC.bnf)
+
+## 今後の展望
+音量やエフェクトなどを指定できるように仕様を拡張する可能性があります。  

docs/markdowns/start/format.md

@@ -0,0 +1,43 @@
+# 利用できるフォーマットについて
+
+SoundMakerでは、以下の形式のWAV出力に対応しています。
+
+### 出力形式
+
+**サンプリング周波数**
+- 48000Hz
+- 44100Hz
+
+**量子化ビット数**
+- 16bit
+- 8bit
+
+**チャンネル数**
+- Stereo 2ch
+- Monaural 1ch
+
+## FormatBuilderの使い方
+
+SoundMakerでは、簡単にフォーマットデータを扱うためのビルダクラスを提供しています。
+
+### コード例
+```cs
+var builder = FormatBuilder.Create()
+            .WithFrequency(48000)
+            .WithBitDepth(16)
+            .WithChannelCount(2);
+
+// 音声波形生成用フォーマット
+var soundFormat = builder.ToSoundFormat();
+// WAV出力用フォーマット
+var waveFileFormat = builder.ToFormatChunk();
+```
+
+### 詳細な説明
+
+- **サンプリング周波数の設定**: `.WithFrequency(48000)` で、サンプリング周波数を48000Hzに設定します。
+- **量子化ビット数の設定**: `.WithBitDepth(16)` で、量子化ビット数を16bitに設定します。
+- **チャンネル数の設定**: `.WithChannelCount(2)` で、ステレオ（2ch）に設定します。
+- **フォーマットの取得**:
+    - `soundFormat`: `.ToSoundFormat()` メソッドを使用して、音声波形生成用のフォーマットを取得します。
+    - `waveFileFormat`: `.ToFormatChunk()` メソッドを使用して、WAV出力用のフォーマットを取得します。

docs/markdowns/start/gen/channel-base-api.md

@@ -0,0 +1,50 @@
+# チャンネルベースAPIでの音声生成
+
+サウンドチャンネルに音符や休符を挿入することで音声を生成する方法を説明します。
+
+### 概要
+この方法では、複数の音のチャンネルを作成し、それらをミキシングしてステレオ音声を生成します。
+
+### コード例
+```cs
+private static StereoWave MakeStereoWave(SoundFormat format)
+{
+    // 一分間の四分音符の個数
+    int tempo = 100;
+    // まず、音のチャンネルを作成する必要がある。
+    // 現段階では矩形波、三角波、疑似三角波、ロービットノイズに対応している。
+    var rightChannel = new SquareSoundChannel(tempo, format, SquareWaveRatio.Point25, PanType.Right)
+    {
+        // ISoundComponentを実装したクラスのオブジェクトをチャンネルに追加していく。
+        // 現段階では普通の音符、休符、タイ、連符を使うことができる。
+        new Note(Scale.C, 5, LengthType.Eighth, isDotted: true),
+        new Tie(new Note(Scale.D, 5, LengthType.Eighth), LengthType.Eighth),
+        new Tuplet(GetComponents(), LengthType.Quarter)
+    };
+    var rightChannel2 = new SquareSoundChannel(tempo, format, SquareWaveRatio.Point125, PanType.Right)
+    {
+        new Note(Scale.C, 4, LengthType.Eighth, isDotted: true),
+        new Note(Scale.D, 4, LengthType.Quarter),
+        new Rest(LengthType.Quarter)
+    };
+    var leftChannel = new TriangleSoundChannel(tempo, format, PanType.Left)
+    {
+        new Note(Scale.C, 3, LengthType.Eighth, isDotted: true),
+        new Note(Scale.D, 3, LengthType.Quarter),
+        new Rest(LengthType.Quarter)
+    };
+    var channels = new List<ISoundChannel>() { rightChannel, rightChannel2, leftChannel };
+    // ミックスは'StereoMixer'クラスで行う。 
+    return new StereoMixer(channels).Mix();
+}
+```
+
+### 詳細な説明
+
+- **テンポ設定**: `tempo` は1分間に演奏される四分音符の数を示しています。ここでは100に設定されています。
+- **チャンネルの作成**:
+    - `rightChannel`: 矩形波のサウンドチャンネル。右パンに設定されています。ドット付き八分音符、タイ、連符が含まれています。
+    - `rightChannel2`: 矩形波の別チャンネル。異なる周波数（`SquareWaveRatio.Point125`）で設定されています。
+    - `leftChannel`: 三角波のサウンドチャンネル。左パンに設定されています。
+- **ISoundComponent** を実装したクラスのオブジェクト（`Note`、`Tie`、`Tuplet`、`Rest`など）をチャンネルに追加しています。
+- **ミキシング**: 最後に、これらのチャンネルを `StereoMixer` クラスでミックスし、ステレオ音声を生成します。

docs/markdowns/start/gen/frequency.md

@@ -0,0 +1,29 @@
+# 周波数を指定し、音声波形を生成する
+
+周波数を直接指定して音波を生成する方法です。以下のプログラムでは、800Hzの三角波を5秒間生成します。
+
+### 概要
+指定された周波数の音波を生成するためのコードです。指定秒数分の配列の長さは `サンプリング周波数 * 秒数` で求められます。
+
+### コード例
+```cs
+private static StereoWave MakeStereoWave(SoundFormat format)
+{
+    var triangleWave = new TriangleWave();
+    int hertz = 800;
+    int length = (int)format.SamplingFrequency * 5;
+    int volume = 50;
+
+    var waveShorts = triangleWave.GenerateWave(format, length, volume, hertz);
+    return new StereoWave(waveShorts, waveShorts);
+}
+```
+
+### 詳細な説明
+
+- **三角波の作成**: `TriangleWave` クラスのインスタンスを作成します。
+- **周波数の設定**: `hertz` は生成する音波の周波数を指定します。ここでは800Hzに設定されています。
+- **配列の長さの計算**: `length` は `サンプリング周波数 * 秒数` で計算されます。ここでは5秒間の音波を生成するため、 `format.SamplingFrequency * 5` となります。
+- **音量の設定**: `volume` で音量を指定します。ここでは50に設定されています(0 <= volume <= 100)。
+- **音波の生成**: `triangleWave.GenerateWave` メソッドを使って、指定された周波数と音量で音波を生成します。
+- **ステレオ音波の作成**: 最後に、生成された音波データを使って `StereoWave` のインスタンスを作成します。