tweaks

Author: zh1peng

docs/.doctrees/environment.pickle

@@ -222,7 +222,7 @@ translated_config = client.translate_config(
 ```
 More details can be found in {doc}`LLMs <LLMs>`.
 
-### ⚠️ Important Notes ⚠️
+### 3. Important Notes on Task Localization
 
 1. **Always review the auto-translated content.** While LLM-based translation performs well in most cases, it's strongly recommended to have a native speaker verify the accuracy and cultural appropriateness of the translated text.
 
@@ -234,5 +234,5 @@ More details can be found in {doc}`LLMs <LLMs>`.
    1. Delete the original voice files in the `assets/` folder.
    2. Regenerate the audio using a TTS voice that matches the target language.
 
-    See {doc}`text2voice <text2voice>` for details on how to configure voices and view the list of supported options.
+    See {doc}`Text-to-Voice <text2voice>` for details on how to configure voices and view the list of supported options.
 

docs/.doctrees/localization.doctree

@@ -1,41 +1,28 @@
-
 ## Text-to-Voice Conversion
 
-`psyflow` supports **text-to-speech (TTS)** conversion to enhance accessibility and standardize instruction delivery across different languages. This would:
-
-**Why it matters**
-- Improves accessibility — especially for children, elderly, or low-literacy participants.  
-- Ensures consistent voice delivery across localized versions.  
-- Avoids the hassle of recording human voiceovers for each translation.  
-
-**How It Works**
+`Psyflow` supports **text-to-speech (TTS)** conversion to enhance accessibility and standardize instruction delivery across different languages. 
 
-PsyFlow uses Microsoft's `edge-tts`, a cloud-based TTS API that converts text to audio (MP3). Voice files are:
+**Why it matters**: Using text-to-speech improves accessibility—especially for children, elderly individuals, or participants with low literacy. It ensures consistent voice delivery across different language versions and eliminates the need to record human voiceovers for each translation. Moreover, by using standardized synthetic voices, it reduces variability introduced by different experimenters (主试), helping to maintain consistency across sessions and sites.
 
-- Stored in the `assets/` folder.
-- Automatically skipped if already generated (unless `overwrite=True`).
-- Registered into `StimBank` as new `Sound` stimuli ready for playback.
+**How It Works**: `Psyflow` uses Microsoft's `edge-tts`, a cloud-based TTS API that converts text to audio (MP3). The generated voice files are stored in the `assets/` folder, automatically skipped if they already exist (unless `overwrite=True` is specified), and registered into the `StimBank` as new `Sound` stimuli ready for playback.
 
-> ⚠️ **Note**: An internet connection is required for TTS generation. Offline tools exist but produce lower-quality audio.
+> **Note**: An internet connection is required for TTS generation. Offline tools exist but produce lower-quality audio.
 
 
-### Basic Usage
-
-#### Convert Existing Text Stimuli to Voice
+### Convert Existing Text Stimuli to Voice
 
 ```python
 from psyflow import StimBank
 stim_bank = StimBank(config)
 stim_bank.convert_to_voice(keys=["instruction_text", "good_bye"], 
 voice="zh-CN-YunyangNeural")
 ```
+This will create audio files like `instruction_text_voice.mp3` in `assets/`.
+ The resulting voices will be registered as `instruction_text_voice`, `good_bye_voice` in `StimBank`.
+
 
-- This will create audio files like `instruction_text_voice.mp3` in `assets/`.
-- The resulting voices will be registered as `instruction_text_voice`, `good_bye_voice` in `StimBank`.
+>If you plan to use voice output, make sure to delete any previously generated audio files in the `assets/` folder before generating new ones. Additionally, choose a TTS voice that matches the language of the text to ensure natural and accurate pronunciation. By default, "zh-CN-XiaoxiaoNeural" is used.
 
-If you plan to use voice:
-1. Delete any previously generated audio in `assets/` before regenerating.
-2. Choose a TTS voice that matches the language of the text.
 
 ---
 
@@ -50,10 +37,8 @@ stim_bank.add_voice(
     voice="ja-JP-NanamiNeural"
 )
 ```
+The result will be registered as `welcome_voice` and available like any other stimulus.
 
-- The result will be registered as `welcome_voice` and available like any other stimulus.
-
----
 
 ### Voice Selection
 
@@ -63,7 +48,7 @@ Use the built-in helper to explore available voices:
 from psyflow.tts_utils import list_supported_voices
 
 # Print all voices
-list_supported_voices(filter_lang="ja", human_readable=True)
+list_supported_voices(human_readable=True)
 
 # Print all Japanese voices
 list_supported_voices(filter_lang="ja", human_readable=True)
@@ -84,12 +69,16 @@ Alternatively, you can check the list of supported voices [here](https://gist.gi
 
 - **Placeholder Limitation**: The TTS engine does **not** support dynamic text with placeholders such as `{duration}` or `{block_num}`. If your text includes placeholders, it will not be converted as expected — the synthesis may fail or result in unnatural output.
 
--  **Overwrite**: Use `overwrite=True` to regenerate voice files even if they exist. However, be careful with this option, as it assumes you need to regenerate the voice every time you run the task ⚠️.
--  **Voice Mismatch**: Always match the voice language to the text language to avoid unnatural pronunciation.
+- **Internet Connection Required**: TTS generation relies on Microsoft’s cloud service and requires a stable internet connection. If you're offline or behind a restrictive network (e.g., with proxy issues), voice generation will fail.
+
+- **Overwrite**: Use `overwrite=True` to regenerate voice files even if they exist. However, be careful with this option, as it assumes you need to regenerate the voice every time you run the task ⚠️.
+
+- **Voice Mismatch**: Always match the voice language to the text language to avoid unnatural pronunciation. By default, "zh-CN-XiaoxiaoNeural" is used.
 
 - **Preview Your Audio**: You can test output files manually in the `assets/` folder before running full experiments.  
   If a file is empty or not playable, it may cause the task to fail at runtime — try deleting and regenerating the voice file.
 
 
 
 
+

docs/.doctrees/text2voice.doctree

@@ -462,8 +462,8 @@ <h2>2. Programmatic Localization via API<a class="headerlink" href="#programmati
 </div>
 <p>More details can be found in <a class="reference internal" href="LLMs.html"><span class="doc">LLMs</span></a>.</p>
 </section>
-<section id="important-notes">
-<h2>⚠️ Important Notes ⚠️<a class="headerlink" href="#important-notes" title="Link to this heading">¶</a></h2>
+<section id="important-notes-on-task-localization">
+<h2>3. Important Notes on Task Localization<a class="headerlink" href="#important-notes-on-task-localization" title="Link to this heading">¶</a></h2>
 <ol class="arabic">
 <li><p><strong>Always review the auto-translated content.</strong> While LLM-based translation performs well in most cases, it’s strongly recommended to have a native speaker verify the accuracy and cultural appropriateness of the translated text.</p></li>
 <li><p><strong>Leverage text-to-speech (TTS) for multilingual audio delivery.</strong><br />
@@ -473,7 +473,7 @@ <h2>⚠️ Important Notes ⚠️<a class="headerlink" href="#important-notes" t
 <li><p>Delete the original voice files in the <code class="docutils literal notranslate"><span class="pre">assets/</span></code> folder.</p></li>
 <li><p>Regenerate the audio using a TTS voice that matches the target language.</p></li>
 </ol>
-<p>See <a class="reference internal" href="text2voice.html"><span class="doc">text2voice</span></a> for details on how to configure voices and view the list of supported options.</p>
+<p>See <a class="reference internal" href="text2voice.html"><span class="doc">Text-to-Voice</span></a> for details on how to configure voices and view the list of supported options.</p>
 </li>
 </ol>
 </section>
@@ -519,7 +519,7 @@ <h2>⚠️ Important Notes ⚠️<a class="headerlink" href="#important-notes" t
 <li><a class="reference internal" href="#">Task Localization</a><ul>
 <li><a class="reference internal" href="#manual-adaptation-quick-and-easy">1. Manual Adaptation (Quick and Easy)</a></li>
 <li><a class="reference internal" href="#programmatic-localization-via-api">2. Programmatic Localization via API</a></li>
-<li><a class="reference internal" href="#important-notes">⚠️ Important Notes ⚠️</a></li>
+<li><a class="reference internal" href="#important-notes-on-task-localization">3. Important Notes on Task Localization</a></li>
 </ul>
 </li>
 </ul>

docs/_sources/localization.md.txt

@@ -247,43 +247,25 @@
         <article role="main" id="furo-main-content">
           <section id="text-to-voice-conversion">
 <h1>Text-to-Voice Conversion<a class="headerlink" href="#text-to-voice-conversion" title="Link to this heading">¶</a></h1>
-<p><code class="docutils literal notranslate"><span class="pre">psyflow</span></code> supports <strong>text-to-speech (TTS)</strong> conversion to enhance accessibility and standardize instruction delivery across different languages. This would:</p>
-<p><strong>Why it matters</strong></p>
-<ul class="simple">
-<li><p>Improves accessibility — especially for children, elderly, or low-literacy participants.</p></li>
-<li><p>Ensures consistent voice delivery across localized versions.</p></li>
-<li><p>Avoids the hassle of recording human voiceovers for each translation.</p></li>
-</ul>
-<p><strong>How It Works</strong></p>
-<p>PsyFlow uses Microsoft’s <code class="docutils literal notranslate"><span class="pre">edge-tts</span></code>, a cloud-based TTS API that converts text to audio (MP3). Voice files are:</p>
-<ul class="simple">
-<li><p>Stored in the <code class="docutils literal notranslate"><span class="pre">assets/</span></code> folder.</p></li>
-<li><p>Automatically skipped if already generated (unless <code class="docutils literal notranslate"><span class="pre">overwrite=True</span></code>).</p></li>
-<li><p>Registered into <code class="docutils literal notranslate"><span class="pre">StimBank</span></code> as new <code class="docutils literal notranslate"><span class="pre">Sound</span></code> stimuli ready for playback.</p></li>
-</ul>
+<p><code class="docutils literal notranslate"><span class="pre">Psyflow</span></code> supports <strong>text-to-speech (TTS)</strong> conversion to enhance accessibility and standardize instruction delivery across different languages.</p>
+<p><strong>Why it matters</strong>: Using text-to-speech improves accessibility—especially for children, elderly individuals, or participants with low literacy. It ensures consistent voice delivery across different language versions and eliminates the need to record human voiceovers for each translation. Moreover, by using standardized synthetic voices, it reduces variability introduced by different experimenters (主试), helping to maintain consistency across sessions and sites.</p>
+<p><strong>How It Works</strong>: <code class="docutils literal notranslate"><span class="pre">Psyflow</span></code> uses Microsoft’s <code class="docutils literal notranslate"><span class="pre">edge-tts</span></code>, a cloud-based TTS API that converts text to audio (MP3). The generated voice files are stored in the <code class="docutils literal notranslate"><span class="pre">assets/</span></code> folder, automatically skipped if they already exist (unless <code class="docutils literal notranslate"><span class="pre">overwrite=True</span></code> is specified), and registered into the <code class="docutils literal notranslate"><span class="pre">StimBank</span></code> as new <code class="docutils literal notranslate"><span class="pre">Sound</span></code> stimuli ready for playback.</p>
 <blockquote>
-<div><p>⚠️ <strong>Note</strong>: An internet connection is required for TTS generation. Offline tools exist but produce lower-quality audio.</p>
+<div><p><strong>Note</strong>: An internet connection is required for TTS generation. Offline tools exist but produce lower-quality audio.</p>
 </div></blockquote>
-<section id="basic-usage">
-<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Link to this heading">¶</a></h2>
 <section id="convert-existing-text-stimuli-to-voice">
-<h3>Convert Existing Text Stimuli to Voice<a class="headerlink" href="#convert-existing-text-stimuli-to-voice" title="Link to this heading">¶</a></h3>
+<h2>Convert Existing Text Stimuli to Voice<a class="headerlink" href="#convert-existing-text-stimuli-to-voice" title="Link to this heading">¶</a></h2>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">psyflow</span><span class="w"> </span><span class="kn">import</span> <span class="n">StimBank</span>
 <span class="n">stim_bank</span> <span class="o">=</span> <span class="n">StimBank</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
 <span class="n">stim_bank</span><span class="o">.</span><span class="n">convert_to_voice</span><span class="p">(</span><span class="n">keys</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;instruction_text&quot;</span><span class="p">,</span> <span class="s2">&quot;good_bye&quot;</span><span class="p">],</span> 
 <span class="n">voice</span><span class="o">=</span><span class="s2">&quot;zh-CN-YunyangNeural&quot;</span><span class="p">)</span>
 </pre></div>
 </div>
-<ul class="simple">
-<li><p>This will create audio files like <code class="docutils literal notranslate"><span class="pre">instruction_text_voice.mp3</span></code> in <code class="docutils literal notranslate"><span class="pre">assets/</span></code>.</p></li>
-<li><p>The resulting voices will be registered as <code class="docutils literal notranslate"><span class="pre">instruction_text_voice</span></code>, <code class="docutils literal notranslate"><span class="pre">good_bye_voice</span></code> in <code class="docutils literal notranslate"><span class="pre">StimBank</span></code>.</p></li>
-</ul>
-<p>If you plan to use voice:</p>
-<ol class="arabic simple">
-<li><p>Delete any previously generated audio in <code class="docutils literal notranslate"><span class="pre">assets/</span></code> before regenerating.</p></li>
-<li><p>Choose a TTS voice that matches the language of the text.</p></li>
-</ol>
-</section>
+<p>This will create audio files like <code class="docutils literal notranslate"><span class="pre">instruction_text_voice.mp3</span></code> in <code class="docutils literal notranslate"><span class="pre">assets/</span></code>.
+The resulting voices will be registered as <code class="docutils literal notranslate"><span class="pre">instruction_text_voice</span></code>, <code class="docutils literal notranslate"><span class="pre">good_bye_voice</span></code> in <code class="docutils literal notranslate"><span class="pre">StimBank</span></code>.</p>
+<blockquote>
+<div><p>If you plan to use voice output, make sure to delete any previously generated audio files in the <code class="docutils literal notranslate"><span class="pre">assets/</span></code> folder before generating new ones. Additionally, choose a TTS voice that matches the language of the text to ensure natural and accurate pronunciation. By default, “zh-CN-XiaoxiaoNeural” is used.</p>
+</div></blockquote>
 </section>
 <hr class="docutils" />
 <section id="add-voice-from-custom-text">
@@ -296,18 +278,15 @@ <h2>Add Voice from Custom Text<a class="headerlink" href="#add-voice-from-custom
 <span class="p">)</span>
 </pre></div>
 </div>
-<ul class="simple">
-<li><p>The result will be registered as <code class="docutils literal notranslate"><span class="pre">welcome_voice</span></code> and available like any other stimulus.</p></li>
-</ul>
+<p>The result will be registered as <code class="docutils literal notranslate"><span class="pre">welcome_voice</span></code> and available like any other stimulus.</p>
 </section>
-<hr class="docutils" />
 <section id="voice-selection">
 <h2>Voice Selection<a class="headerlink" href="#voice-selection" title="Link to this heading">¶</a></h2>
 <p>Use the built-in helper to explore available voices:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">psyflow.tts_utils</span><span class="w"> </span><span class="kn">import</span> <span class="n">list_supported_voices</span>
 
 <span class="c1"># Print all voices</span>
-<span class="n">list_supported_voices</span><span class="p">(</span><span class="n">filter_lang</span><span class="o">=</span><span class="s2">&quot;ja&quot;</span><span class="p">,</span> <span class="n">human_readable</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<span class="n">list_supported_voices</span><span class="p">(</span><span class="n">human_readable</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
 
 <span class="c1"># Print all Japanese voices</span>
 <span class="n">list_supported_voices</span><span class="p">(</span><span class="n">filter_lang</span><span class="o">=</span><span class="s2">&quot;ja&quot;</span><span class="p">,</span> <span class="n">human_readable</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
@@ -358,8 +337,9 @@ <h2>Voice Selection<a class="headerlink" href="#voice-selection" title="Link to
 <h2>Tips and Caveats<a class="headerlink" href="#tips-and-caveats" title="Link to this heading">¶</a></h2>
 <ul class="simple">
 <li><p><strong>Placeholder Limitation</strong>: The TTS engine does <strong>not</strong> support dynamic text with placeholders such as <code class="docutils literal notranslate"><span class="pre">{duration}</span></code> or <code class="docutils literal notranslate"><span class="pre">{block_num}</span></code>. If your text includes placeholders, it will not be converted as expected — the synthesis may fail or result in unnatural output.</p></li>
+<li><p><strong>Internet Connection Required</strong>: TTS generation relies on Microsoft’s cloud service and requires a stable internet connection. If you’re offline or behind a restrictive network (e.g., with proxy issues), voice generation will fail.</p></li>
 <li><p><strong>Overwrite</strong>: Use <code class="docutils literal notranslate"><span class="pre">overwrite=True</span></code> to regenerate voice files even if they exist. However, be careful with this option, as it assumes you need to regenerate the voice every time you run the task ⚠️.</p></li>
-<li><p><strong>Voice Mismatch</strong>: Always match the voice language to the text language to avoid unnatural pronunciation.</p></li>
+<li><p><strong>Voice Mismatch</strong>: Always match the voice language to the text language to avoid unnatural pronunciation. By default, “zh-CN-XiaoxiaoNeural” is used.</p></li>
 <li><p><strong>Preview Your Audio</strong>: You can test output files manually in the <code class="docutils literal notranslate"><span class="pre">assets/</span></code> folder before running full experiments.<br />
 If a file is empty or not playable, it may cause the task to fail at runtime — try deleting and regenerating the voice file.</p></li>
 </ul>
@@ -404,10 +384,7 @@ <h2>Tips and Caveats<a class="headerlink" href="#tips-and-caveats" title="Link t
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Text-to-Voice Conversion</a><ul>
-<li><a class="reference internal" href="#basic-usage">Basic Usage</a><ul>
 <li><a class="reference internal" href="#convert-existing-text-stimuli-to-voice">Convert Existing Text Stimuli to Voice</a></li>
-</ul>
-</li>
 <li><a class="reference internal" href="#add-voice-from-custom-text">Add Voice from Custom Text</a></li>
 <li><a class="reference internal" href="#voice-selection">Voice Selection</a></li>
 <li><a class="reference internal" href="#tips-and-caveats">Tips and Caveats</a></li>