LearnPY

LearnPY - Pinyin Learning App
© 2025 OneShama Studio. All rights reserved.

A simplified, open-source educational app for learning Mandarin Chinese Pinyin pronunciation.

---

About This Repository

LearnPy is a simplified, educational version derived from the LexiGo (LearnZh) app, specifically designed for:

• Interactive Pinyin Learning: Master the fundamentals of Mandarin Chinese pronunciation
• Tutorial Mode: Step-by-step guided learning experience
• Audio Pronunciation: High-quality pronunciation examples for all Pinyin combinations
• Open Source Education: Supporting accessible language learning worldwide

This repository provides all codes and static resource we used in building LearnPy.

---

About PinYin Audio Resource

PinYin audio resource comes from Tone Perfect dataset.

Catherine Ryu, Mandarin Tone Perception & Production Team,
and Michigan State University Libraries Digital Collections Team (2017). Tone Perfect (https://tone.lib.msu.edu/).

We gratefully acknowledge professor Ryu and Tone Perfect project team for providing high quality PinYin audio resource.

Notice: We didn't include the project audio files in this repository. To build a same app with PinYin pronunciation function by utilizing this repository, you need to provide audio resource. See How to utilize for details.

---

How to utilize

Follow these steps to set up and build LearnPY with full audio functionality:

1. Clone the Repository

# Clone the LearnPY repository
git clone https://github.com/Fan-7SZ/LearnPy.git
cd LearnPY

2. Create Xcode Project and Import Files

1. Open Xcode and create a new iOS project:

   • Choose "iOS" → "App"
   • Product Name: LearnPY
   • Interface: SwiftUI
   • Language: Swift

2. Import repository files:

   • Delete the default ContentView.swift and other generated files
   • Drag and drop all folders from the cloned repository into your Xcode project
   • Ensure "Copy items if needed" is checked
   • Add files to your app target
   • Add swift-markdown-ui package

Notice: Ensure Xcode has regarded Resource folder as an entity. There should be a target linking the whole folder to LearnPy. You can check whether Copy Bundle Resources setting looked like the following screenshot.

3. Add the custom fonts to your project's Info.plist:

<key>UIAppFonts</key>
<array>
    <string>Resource/Fonts/Nunito-VariableFont_wght.ttf</string>
    <string>Resource/Fonts/SourceSans3VF-Upright.otf</string>
</array>

Or in Xcode's Info tab, add a new row:

• Key: Fonts provided by application (UIAppFonts)
• Value: Array with font filenames

4. Add Audio Files

LearnPY expects audio files with specific naming conventions in the Resource/Audio/PinYin/ directory.

4.1 Using Tone Perfect Audio Files (Recommended)

If you have access to Tone Perfect dataset, the files should be named:

{pinyin}_MV1_MP3.mp3

Examples:

a1_MV1_MP3.mp3    // First tone 'ā'
bo1_MV1_MP3.mp3   // 'bo' with first tone
chi1_MV1_MP3.mp3  // 'chi' with first tone
yang1_MV1_MP3.mp3 // 'yang' with first tone

4.2 Using Alternative Audio Sources

If you're using different audio files, you have two options:

Option A: Rename your files to match the expected format:

# Example: Rename your files to match Tone Perfect convention
mv your_a_tone1.mp3 a1_MV1_MP3.mp3
mv your_bo_tone1.mp3 bo1_MV1_MP3.mp3

Option B: Modify the code in AudioPlayer/playPinyin.swift:

// Current code (line ~34):
guard let url = Bundle.main.url(
    forResource: fileName + "_MV1_MP3", // ← Modify this suffix
    withExtension: "mp3", 
    subdirectory: "Resource/Audio/PinYin/"
) else {

// Example modifications for different naming conventions:

// For files named like "a1.mp3", "bo1.mp3":
forResource: fileName,

// For files named like "a1_audio.mp3", "bo1_audio.mp3":
forResource: fileName + "_audio",

// For files named like "pinyin_a1.mp3", "pinyin_bo1.mp3":
forResource: "pinyin_" + fileName,

4.3 Required Audio Files

The app expects audio files for all entries in the mapPy dictionary (see AudioPlayer/playPinyin.swift). Key files include:

Tones:

• a1_MV1_MP3.mp3, a2_MV1_MP3.mp3, a3_MV1_MP3.mp3, a4_MV1_MP3.mp3

Initials:

• bo1_MV1_MP3.mp3, po1_MV1_MP3.mp3, mo1_MV1_MP3.mp3, fou1_MV1_MP3.mp3
• de1_MV1_MP3.mp3, te1_MV1_MP3.mp3, ne1_MV1_MP3.mp3, le1_MV1_MP3.mp3
• And more... (see full list in mapPy dictionary)

Finals:

• ai1_MV1_MP3.mp3, ao1_MV1_MP3.mp3, an1_MV1_MP3.mp3, ang1_MV1_MP3.mp3
• ei1_MV1_MP3.mp3, en1_MV1_MP3.mp3, eng1_MV1_MP3.mp3
• And more... (see full list in mapPy dictionary)

5. Build and Run

1. Select your target device or simulator
2. Press Cmd + R to build and run
3. Test audio playback by tapping any Pinyin element

6. Troubleshooting

Audio not playing:

• Check that audio files are correctly named and located in Resource/Audio/PinYin/
• Verify the file naming convention matches your code modification
• Ensure audio files are added to the Xcode project target

Font not displaying:

• Verify font files are added to the project
• Check that font names in Info.plist match the actual font file names
• Test font loading in FontStyle.swift

Build errors:

• Clean build folder (Cmd + Shift + K)
• Ensure all Swift files are added to the target
• Check for missing imports or dependencies

---

Open Source License

LearnPy and relevant resource are under MIT license. See LICENSE.md for details.

---

Support & Feedback

• Issues & Suggestions: Report on GitHub or contact support
• General Support: support@oneshama.com

---

Start your Pinyin learning journey with LearnPY