refactor: モーラと音素長に関する docstring を明確化 (#1680)

Author: tarepan

test/e2e/__snapshots__/test_openapi/test_OpenAPIの形が変わっていないことを確認.json

@@ -212,7 +212,7 @@ def accent_phrases(
     @router.post(
         "/mora_data",
         tags=["クエリ編集"],
-        summary="アクセント句から音高・音素長を得る",
+        summary="アクセント句から音素の長さと音高を得る",
     )
     def mora_data(
         accent_phrases: list[AccentPhrase],
@@ -226,7 +226,7 @@ def mora_data(
     @router.post(
         "/mora_length",
         tags=["クエリ編集"],
-        summary="アクセント句から音素長を得る",
+        summary="アクセント句から音素の長さを得る",
     )
     def mora_length(
         accent_phrases: list[AccentPhrase],

voicevox_engine/app/routers/tts_pipeline.py

@@ -786,7 +786,7 @@ def predict_sing_consonant_length_forward(
         style_id: NDArray[np.int64],
     ) -> NDArray[np.int64]:
         """
-        子音・母音列から音素ごとの長さを求める。
+        子音列の各子音の長さを求める。
 
         Parameters
         ----------
@@ -804,7 +804,7 @@ def predict_sing_consonant_length_forward(
         Returns
         -------
         output : NDArray[np.int64]
-            子音長
+            子音の長さ
         """
         if self.api_exists["predict_sing_consonant_length_forward"]:
             output = np.zeros((length,), dtype=np.int64)

voicevox_engine/core/core_wrapper.py

@@ -70,18 +70,9 @@ def _text_to_accent_phrase(phrase: str) -> AccentPhrase:
     """
     単一アクセント句に相当するAquesTalk 風記法テキストからアクセント句オブジェクトを生成する。
 
-    longest matchによりモーラ化。入力長Nに対し計算量O(N^2)。
-
-    Parameters
-    ----------
-    phrase : str
-        単一アクセント句に相当するAquesTalk 風記法テキスト
-
-    Returns
-    -------
-    accent_phrase : AccentPhrase
-        アクセント句
+    音素長と音高は0で初期化する。
     """
+    # NOTE: longest matchによりモーラ化。入力長Nに対し計算量O(N^2)。
     # NOTE: ポーズと疑問形はこの関数内で処理しない
 
     accent_index: int | None = None
@@ -135,17 +126,9 @@ def _text_to_accent_phrase(phrase: str) -> AccentPhrase:
 
 def parse_kana(text: str) -> list[AccentPhrase]:
     """
-    AquesTalk 風記法テキストからアクセント句系列を生成
+    AquesTalk 風記法テキストからアクセント句系列を生成する。
 
-    Parameters
-    ----------
-    text : str
-        AquesTalk 風記法テキスト
-
-    Returns
-    -------
-    parsed_results : list[AccentPhrase]
-        アクセント句（音素・モーラ音高 0初期化）系列を生成
+    音素長と音高は0で初期化する。
     """
     parsed_results: list[AccentPhrase] = []
     phrase_base = 0
@@ -193,19 +176,7 @@ def parse_kana(text: str) -> list[AccentPhrase]:
 
 
 def create_kana(accent_phrases: list[AccentPhrase]) -> str:
-    """
-    アクセント句系列からAquesTalk 風記法テキストを生成
-
-    Parameters
-    ----------
-    accent_phrases : list[AccentPhrase]
-        アクセント句系列
-
-    Returns
-    -------
-    text : str
-        AquesTalk 風記法テキスト
-    """
+    """アクセント句系列からAquesTalk 風記法テキストを生成する。"""
     text = ""
     # アクセント句を先頭から逐次パースし、`text`末尾にAquesTalk 風記法の文字を都度追加（ループ）
     for i, phrase in enumerate(accent_phrases):

voicevox_engine/tts_pipeline/kana_converter.py

@@ -23,13 +23,11 @@ class Mora(BaseModel):
         default=None, description="子音の音素"
     )
     consonant_length: float | SkipJsonSchema[None] = Field(
-        default=None, description="子音の音長"
+        default=None, description="子音の長さ"
     )
     vowel: str = Field(description="母音の音素")
-    vowel_length: float = Field(description="母音の音長")
-    pitch: float = Field(
-        description="音高"
-    )  # デフォルト値をつけるとts側のOpenAPIで生成されたコードの型がOptionalになる
+    vowel_length: float = Field(description="母音の長さ")
+    pitch: float = Field(description="音高")
 
     def __hash__(self) -> int:
         """内容に対して一意なハッシュ値を返す。"""

voicevox_engine/tts_pipeline/model.py

@@ -353,7 +353,11 @@ def mora_to_text(mora_phonemes: str) -> str:
 
 
 def _mora_labels_to_moras(mora_labels: list[MoraLabel]) -> list[Mora]:
-    """MoraLabel系列をMora系列へキャストする。音素長と音高は 0 初期化"""
+    """
+    MoraLabel系列をMora系列へキャストする。
+
+    音素長と音高は0で初期化する。
+    """
     return [
         Mora(
             text=mora_to_text("".join([label.phoneme for label in mora.labels])),

voicevox_engine/tts_pipeline/text_analyzer.py

@@ -70,7 +70,7 @@ def _create_one_hot(accent_phrase: AccentPhrase, index: int) -> NDArray[np.int64
 
 
 def _generate_silence_mora(length: float) -> Mora:
-    """無音モーラの生成"""
+    """音の長さを指定して無音モーラを生成する。"""
     return Mora(text="　", vowel="sil", vowel_length=length, pitch=0.0)
 
 
@@ -246,7 +246,7 @@ def supported_devices(self) -> DeviceSupport | None:
     def update_length(
         self, accent_phrases: list[AccentPhrase], style_id: StyleId
     ) -> list[AccentPhrase]:
-        """アクセント句系列に含まれるモーラの音素長属性をスタイルに合わせて更新する"""
+        """アクセント句系列に含まれる音素の長さをスタイルに合わせて更新する。"""
         # モーラ系列を抽出する
         moras = to_flatten_moras(accent_phrases)
 
@@ -256,10 +256,10 @@ def update_length(
         # 音素クラスから音素IDスカラへ表現を変換する
         phoneme_ids = np.array([p.id for p in phonemes], dtype=np.int64)
 
-        # コアを用いて音素長を生成する
+        # 音素ごとの長さを生成する
         phoneme_lengths = self._core.safe_yukarin_s_forward(phoneme_ids, style_id)
 
-        # 生成結果でモーラ内の音素長属性を置換する
+        # 生成された音素長でモーラの音素長を更新する
         vowel_indexes = [i for i, p in enumerate(phonemes) if p.is_mora_tail()]
         for i, mora in enumerate(moras):
             if mora.consonant is None:
@@ -273,7 +273,7 @@ def update_length(
     def update_pitch(
         self, accent_phrases: list[AccentPhrase], style_id: StyleId
     ) -> list[AccentPhrase]:
-        """アクセント句系列に含まれるモーラの音高属性をスタイルに合わせて更新する"""
+        """アクセント句系列に含まれるモーラの音高をスタイルに合わせて更新する。"""
         # 後続のnumpy.concatenateが空リストだとエラーになるので別処理
         if len(accent_phrases) == 0:
             return []
@@ -340,7 +340,7 @@ def update_pitch(
     def update_length_and_pitch(
         self, accent_phrases: list[AccentPhrase], style_id: StyleId
     ) -> list[AccentPhrase]:
-        """アクセント句系列の音素長・モーラ音高をスタイルIDに基づいて更新する"""
+        """アクセント句系列に含まれる音素の長さとモーラの音高をスタイルに合わせて更新する。"""
         accent_phrases = self.update_length(accent_phrases, style_id)
         accent_phrases = self.update_pitch(accent_phrases, style_id)
         return accent_phrases