Skip to content

docs(readme): 「30秒で試す」を OS 別ワンライナー化 + CLI バイナリ選択ガイド追加 (#359) - #360

Merged
ayutaz merged 5 commits into
devfrom
docs/issue-359-readme-quickstart
Apr 26, 2026
Merged

docs(readme): 「30秒で試す」を OS 別ワンライナー化 + CLI バイナリ選択ガイド追加 (#359)#360
ayutaz merged 5 commits into
devfrom
docs/issue-359-readme-quickstart

Conversation

@ayutaz

@ayutaz ayutaz commented Apr 26, 2026

Copy link
Copy Markdown
Owner

Summary

Closes #359

Zenn スクラップ (kun432 氏) で指摘されていた以下の README の問題を解消:

  • 「30秒で試す」にダウンロードコマンドが無く、Mac で piper-macos-arm64.tar.gz (C++) と piper-plus-cli-osx-arm64.tar.gz (C#) のどちらを選べばよいか分からない
  • ./piper --download-model tsukuyomi だけ書かれていて、そもそもバイナリをどう取得するかが不明

Changes

README.md / README_EN.md

「30秒で試す」 -> 「方法1: プリビルドバイナリ (推奨)」を以下の4ブロックに置き換え:

  • macOS (Apple Silicon) — curl -L .../piper-macos-arm64.tar.gz | tar xz
  • Linux (x86_64) — curl -L .../piper-linux-x64.tar.gz | tar xz
  • Linux (ARM64, Raspberry Pi 4/5) — curl -L .../piper-linux-arm64.tar.gz | tar xz
  • Windows (PowerShell) — Invoke-WebRequest ... .zip + Expand-Archive

Quick Start には全プラットフォーム最広対応の C++ CLI (piper-*) を採用し、末尾に「どのバイナリを選べばよい？」案内 + バイナリ選択ガイドへのリンクを追加。

docs/getting-started/binary-selection.md (新規)

3つのCLIバリアント (C++ / C# .NET / Rust) の使い分けを詳細解説:

  • 比較表 (実装・特徴・推奨用途)
  • OS x アーキテクチャ対応マトリクス
  • 判断フロー (armv7 -> C++、Intel Mac -> C#、GPU -> Rust など)
  • ダウンロード方法のサンプルコマンド
  • トラブルシューティング (Gatekeeper、libonnxruntime.so、Defender SmartScreen など)

Test plan

  • README.md / README_EN.md の該当セクションが置き換わっていること
  • 新規 docs ファイルが作成されていること
  • README -> binary-selection.md のリンクが正しいパスを指していること
  • (CI で markdown lint / link check が通ること)
  • (レビュアーによる文言・コマンド動作確認)

Out of scope (Issue #359 に書いた C 案)

「README 全体を機能別 docs に分割」の大規模リファクタリングは、リンク切れリスクが高いため本 PR ではスコープアウト。バイナリ選択ガイドの抽出のみ対応。

@ayutaz
docs(readme): 「30秒で試す」を OS 別ワンライナー化 + CLI バイナリ選択ガイド追加 (#359)
c8a1a10 
- README.md / README_EN.md の「30秒で試す」を macOS / Linux x64 / Linux ARM64 / Windows のコピペ可能なコマンドに置き換え
- 3つのCLIバリアント (C++ / C# / Rust) の使い分けを docs/getting-started/binary-selection.md として新設
- README からはサマリー1行 + リンクで誘導
Copilot AI review requested due to automatic review settings April 26, 2026 03:39
Copilot AI reviewed Apr 26, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves the top-level Quick Start experience by adding OS-specific one-liner download/extract commands to the README (JP/EN) and introducing a new guide that explains how to choose between the C++ / C# / Rust CLI binaries shipped in GitHub Releases.

Changes:

  • Replaced the previous “download from Releases” text with OS-specific copy/pasteable Quick Start blocks (macOS / Linux x86_64 / Linux arm64 / Windows).
  • Standardized the Quick Start to use the C++ CLI (piper-*) and added a “which binary should I pick?” pointer to a new guide.
  • Added docs/getting-started/binary-selection.md documenting CLI variants, platform matrix, decision flow, download examples, and troubleshooting tips.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File Description
docs/getting-started/binary-selection.md New documentation for selecting the right CLI binary + download/troubleshooting examples
README.md Japanese Quick Start updated with OS-specific one-liners + link to the binary selection guide
README_EN.md English Quick Start updated with OS-specific one-liners + link to the binary selection guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread README_EN.md Outdated
Comment thread README_EN.md Outdated
Comment thread docs/getting-started/binary-selection.md Outdated
Comment thread docs/getting-started/binary-selection.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
ayutaz added 4 commits April 26, 2026 14:22
@ayutaz
docs(readme): 多言語 README 9言語に Linux ARM64 ブロック + バイナリ選択コールアウト追加 (#359)
42ac808 
DE / ES / FR / HI / KO / PT / RU / SV / ZH の各 README に以下を追加:
- Linux (ARM64, Raspberry Pi 4/5) のダウンロードブロック
- 「どのバイナリを選べばよい？」コールアウト (docs/getting-started/binary-selection.md へのリンク)
@ayutaz
fix(readme): C++ CLI のバイナリパスを ./bin/piper に修正 (Copilot review)
e72e45c 
- README.md / README_EN.md の Quick Start を ./bin/piper および .\bin\piper.exe に
- docs/getting-started/binary-selection.md の C++ 実行例とトラブルシュートを ./bin/piper に
- Linux libonnxruntime.so 対応の LD_LIBRARY_PATH を $(pwd)/lib に修正 (.so は piper/lib/ に同梱)
@ayutaz
docs(readme): 重複していた「30秒で試す」を削除し既存「クイックスタート」に統合 (#359)
58ef81a 
- README.md / README_EN.md の「30秒で試す」(私が追加した) と「クイックスタート」のプリビルドバイナリ
  セクションが完全重複していたため、新規セクションを削除
- 既存「クイックスタート > プリビルドバイナリ (ビルド不要)」に Linux ARM64 ブロックと
  バイナリ選択コールアウトを移植 (多言語 README と同一構造に統一)
- 目次から「30秒で試す」を削除、本文の参照リンクも除去
- 各 README が約 90 行削減 (803 / 787 行)
@ayutaz
docs(readme): README.md / README_EN.md を ~400 行に圧縮し詳細を docs/guides/ に…
1bd5095 
…分離 (#359)

ollama / coqui-ai/TTS など他 OSS の README 構造を参考にリファクタリング。
詳細セクションを docs/guides/ に切り出して、README はクイックスタート中心に。

新規 docs:
- docs/guides/cli-usage.md (149行) — C++ CLI 詳細・JSON入力・モデル管理・環境変数
- docs/guides/training.md (69行) — 学習・ファインチューニング
- docs/guides/pretrained-models.md (69行) — モデル一覧・6言語ベース・日本語TTS
- docs/guides/building-from-source.md (106行) — C++/C#/Rust ソースビルド

README 圧縮:
- 「使い方」「学習」「事前学習済みモデル」「日本語 TTS」「ソースからビルド」の各詳細を docs/ にリンク
- 「主要機能 > ランタイム別機能サポート」テーブル削除、「主要機能 > プラットフォーム」削除
- 「プラットフォーム」H2 を3行サマリーに圧縮
- 死リンクとなった目次「日本語 TTS / Japanese TTS」を削除

行数:
- README.md:    803 -> 398 行 (-405行)
- README_EN.md: 787 -> 393 行 (-394行)
@ayutaz
ayutaz merged commit 3748d60 into dev Apr 26, 2026
14 checks passed
@ayutaz
ayutaz deleted the docs/issue-359-readme-quickstart branch April 26, 2026 11:26
@ayutaz ayutaz mentioned this pull request May 2, 2026
Merged
5 tasks
ayutaz added a commit that referenced this pull request May 3, 2026
@ayutaz
docs: 監査結果に基づくドキュメント全面同期 (v1.11.0 以降の差分を一括反映) (#368)
2bf8dfb 
* docs: 監査結果に基づくドキュメント全面同期

v1.11.0 以降の実装変更 (#321 OpenAI互換API, #331 Voice Cloning/SSML, #337 短文品質, #342 HTS voice除去, #349/#367 phoneme timing/streaming, #361 FastAPI移行, #366 arm64 Docker) が
CHANGELOG・多言語 README・docstring に未反映だった部分を一括同期。新規に C# CLI/Core README を追加。

- ルート CHANGELOG: Unreleased に #360-#366 (FastAPI移行/arm64 Docker/短文崩壊修正/Wyoming HA等) を追記
- 多言語 README 9 ファイル (DE/ES/FR/HI/KO/PT/RU/SV/ZH): Voice Cloning/SSML/Phoneme Timing/Strategy A/B/C/FastAPI を反映
- C# CLI/Core README 新規作成 (src/csharp/PiperPlus.Cli/, PiperPlus.Core/)
- WASM CHANGELOG: [0.3.1] セクション追加 + [0.4.0] 日付修正 (0.3.0 と同日問題解消)
- docstring 補強: http_server.py FastAPI エンドポイント / inference.py OpenAI 互換 API
- HTS voice 残存言及を削除 (windows-setup.md)
- --language-balanced-sampling help を 6 言語対応に更新 (バイリンガル時代の遺物修正)
- Go README: Docker multi-arch (amd64/arm64) + serve サブコマンドのセクション追加
- pretrained-models.md: つくよみちゃん 6lang-v2 / 6lang ベースモデルの詳細追記
- huggingface-space/docker/README: 言語表記/Go arm64 表記の整合修正

* docs: 二次監査で発見した取り残しを追加修正

前回コミット (f212aba) では多言語 README 9 ファイルを更新したが、
ベースとなる README.md (日本語) と README_EN.md には Voice Cloning / SSML / 短文品質改善の bullets を入れ忘れていた。
また Rust piper-core/src/lib.rs のクレートドキュメントが「7 言語 (KO 含むが SV を欠く)」のまま、
8 言語 G2P + 6 言語学習済みモデルという最新の状態を反映していなかった。

- README.md / README_EN.md のインターフェースセクション末尾に Voice Cloning / SSML / 短文品質改善 (Strategy A/B/C) の 3 bullets を追加 (多言語版と同等内容)
- src/rust/piper-core/src/lib.rs:4 のクレートドキュメントを「8 言語 G2P (JA/EN/ZH/KO/ES/FR/PT/SV)、学習済みモデルは 6 言語」に修正

二次監査で誤指摘と判明した項目はスキップ:
- WASM g2p test の "all 7 non-JA languages" は JA を除いた 7 言語の意味で正しい (ALL_NON_JA = en/zh/ko/es/fr/pt/sv)
- C# CLI README の --debug/--quiet/--version はすでに L66 に記載済み

* docs: 低優先度の取り残し項目をすべて対応

二次監査で「低優先度・別 PR 推奨」と棚上げした 5 項目に対応。レガシー API
(BILINGUAL/espeak) の意図と廃止予定を明示し、サンプル/パッケージのバージョン
管理状況をユーザーが誤解しないようドキュメント化する目的。

- Go (src/go/piperplus/config.go): PhonemeTypeEspeak / PhonemeTypeBilingual に
  Deprecated コメント追加 (CONTRIBUTING.md "espeak-ng Policy" / PR #218 への参照付き)
- Python (src/python_run/piper/voice.py): PhonemeType.BILINGUAL 分岐に
  Deprecation 注記 + SV/KO が学習済みモデル未対応の理由をコメント化
- C# (src/csharp/PiperPlus.Core/Config/PiperConfig.cs): Espeak フィールドに
  XML doc 追加 (legacy config.json 互換のみ、新規モデルは null とする旨)
- examples/{c-api,dart,godot}/README.md: CI で実行検証されているか否かを
  各 README 冒頭に明示 (c-api はビルドのみ検証、dart/godot は未検証)
- CONTRIBUTING.md: "Package Versioning Policy" セクション新規追加
  (8 パッケージそれぞれの独立バージョン管理ポリシーとタグ命名規則を表形式で明文化)

実装ロジックには変更なし (コメント・docstring・README のみ)。

* docs: Copilot レビュー指摘 16 件 + 追加発見をすべて対応

Copilot pull-request reviewer が PR #368 に付けた 16 件のレビューコメントと、
それを契機にした再監査で見つかった整合性問題を一括解消。リリース直前の
一貫性確認に過ぎないので、いずれもドキュメント・コメントレベルの調整のみ。

Copilot 指摘 (16件):
- 多言語 README 11 ファイル (README.md/EN/DE/ES/FR/HI/KO/PT/RU/SV/ZH): bullets が
  「7 ランタイム」と書きながら列挙は 6 つだったのを「6 ランタイム」に統一。
  日本語版/英語版は libpiper_plus を C++ にまとめる旨を補足
- docker/python-inference/inference.py: モジュール docstring が定義されていない
  `POST /api/phoneme-timing` を載せ、`/synthesize` を POST と書いていたのを修正
  (該当エンドポイントは src/python_run/piper/http_server.py 側であることも明記)
- src/python/piper_train/__main__.py:255-260: `--language-balanced-sampling` が
  `num_speakers > 1` も必要 (single-speaker は SpeakerBalancedBatchSampler を
  バイパス) という条件を help に追記
- docker/README.md:19: Go Dockerfile 行の base image を `golang:1.22` から
  実際の `golang:1.26` に修正
- src/go/README.md:380-: `docker buildx build` の例に `--load` (single-arch) と
  `--push` (multi-arch) の両パターンを示し、ローカル実行不可だった例を解消
- src/go/README.md:298 / 406: 見出し「## HTTP API / HTTPエンドポイント」を
  「## HTTP API」に変更してアンカーを `#http-api` に統一、リンク
  `[HTTP API](#http-api--http-api)` の broken anchor を修正
- src/csharp/PiperPlus.Core/README.md:34: `new DotNetG2PEngine()` は
  PiperPlus.Cli の `internal sealed class` で外部から呼べないため、
  IJapaneseG2PEngine を持ち込む必要がある旨を明記したサンプルに置換
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs(readme): 「30秒で試す」のバイナリ名混乱とダウンロードコマンド不足を解消

2 participants

@ayutaz