Detailed Workflow Guide

Overview

This guide provides detailed step-by-step instructions for using each application in the Tone Matching Suite. For a quick introduction, see the Getting Started Guide.

1. Tone Matching Bundler

Purpose: Prepare data bundles from your Dekereke database

User: Researcher

Input: Dekereke XML file + WAV audio files

Output: .tncmp bundle file

Step-by-Step Instructions

Step 1: Launch the Application

1. Download and install from the Downloads page
2. Open "Tone Matching Bundler" from your Applications folder or Start Menu
3. The main window will appear with several sections

Step 2: Select Your XML File

1. Click the "Browse" button next to "XML File"
2. Navigate to your Dekereke export file (should end in .xml)
3. Select the file and click "Open"
4. The app will parse the file and show:
   • Number of records found
   • Available fields (columns) in your data

Step 3: Configure Display Settings

1. In the "Display Settings" section, choose which fields to show to speakers:
   • Check boxes next to fields you want displayed (e.g., "Phonetic", "Orthographic")
   • These will appear as the "written form" when speakers are matching
2. Decide if you want to show written forms at all:
   • Check "Show written forms" for speakers who can read
   • Uncheck for audio-only mode (speakers only hear words)

Step 4: Configure Audio Settings

1. Click "Browse" next to "Audio Folder"
2. Select the folder containing your WAV audio files
3. Audio Suffix (Optional):
   • If your audio files have additional text in the name, enter it here
   • Example: XML says "word.wav", but files are "word-phon.wav" → enter "-phon"
   • Leave blank if file names match exactly
4. Audio Processing (Optional):
   • Check "Enable audio processing" to trim silence and convert to FLAC
   • This reduces bundle size by 50-70%
   • Adds processing time but recommended for mobile distribution

Step 5: Filter Records (Optional)

1. In the "Reference Numbers" text box, enter specific record IDs (one per line)
2. Only these records will be included in the bundle
3. Leave blank to include all records
4. Use this to:
   • Work with specific grammatical categories
   • Limit to certain syllable patterns
   • Create focused bundles for training

Step 6: Configure User Input Settings

1. "Require user to type spelling":
   • Check this if you want speakers to enter their own orthography
   • Uncheck if spelling is not needed
2. "User spelling element":
   • Enter the XML element name where user spelling should be stored
   • Example: "UserSpelling" or "NativeSpeakerOrthography"
3. "Tone group element":
   • Enter the XML element name where tone group assignments should be stored
   • Example: "ToneGroup" or "ToneMelody"

Step 7: Create the Bundle

1. Click "Browse" next to "Output Bundle File"
2. Choose a location and filename (e.g., "cvcv_nouns_bundle.tncmp")
3. Click "Create Bundle"
4. Wait for processing:
   • Progress bar will show status
   • With audio processing: may take several minutes
   • Without audio processing: usually under 1 minute
5. Review the results:
   • Any missing audio files will be reported
   • Success message will confirm bundle creation

Tips for Bundler App

• Test with small bundles first: Start with 20-30 words to test your configuration
• Organize by pattern: Create separate bundles for different syllable patterns or categories
• Name meaningfully: Use descriptive names like "cvcv_nouns_speaker1.tncmp"
• Keep originals: Don't delete your original XML and audio files

2. Tone Matching Desktop

Purpose: Classify words by tone melody

User: Native speaker or researcher

Input: .tncmp bundle file

Output: Results zip file with tone group assignments

Step-by-Step Instructions

Step 1: Load a Bundle

1. Launch "Tone Matching Desktop"
2. Click "Open Bundle"
3. Select your .tncmp file
4. Wait for loading (usually a few seconds)
5. The bundle information will appear

Step 2: Start Tone Matching

1. Click "Start Tone Matching"
2. The first word will be displayed

Step 3: Create Your First Tone Group

1. Listen: Click the play button to hear the word
2. Draw: On paper, draw a simple picture representing the tone melody
3. Upload: Click the camera/upload button to select your drawing image
4. Type (if required): Enter your spelling of the word
5. Confirm: The first tone group is created!

Step 4: Classify Remaining Words

For each subsequent word:

1. Listen to current word:
   • Click play button (▶️) next to current word
   • Listen as many times as needed
2. Review existing tone groups:
   • Scroll through tone group cards
   • Each shows: group number, your drawing, member words
   • Click play on member words to compare
3. Make a decision:
   • Matches existing group: Click that tone group card
   • Doesn't match any: Click "Create New Group" at bottom
     • Draw a new picture
     • Upload the image
     • Type spelling if required
4. Automatic advance: App moves to next word

Step 5: Review (Optional)

1. Click "Review" button (if available)
2. Look through each tone group
3. Play all words in a group to verify consistency
4. Adjust if needed (current version has limited reorganization)

Step 6: Export Results

1. When all words are classified, click "Export" or download icon
2. Choose a save location
3. A zip file will be created containing:
   • Updated XML with tone group assignments
   • CSV summary of classifications
   • Metadata about the session

Tips for Tone Matching

• Don't rush: Take time to listen and compare carefully
• Replay often: It's normal to listen 3-5 times before deciding
• Trust your ears: If it sounds the same, it probably is
• When in doubt, create new: It's easier to merge groups later than split them
• Take breaks: Every 30-60 minutes, rest your ears
• Save periodically: Some versions auto-save, but manual saves are good practice

3. Tone Matching Mobile

Purpose: Classify words by tone melody on Android devices

User: Native speaker

Input: .tncmp bundle file

Output: Results zip file

The workflow is very similar to the Desktop app, with these mobile-specific considerations:

Additional Mobile Steps

Installation

1. Enable "Install from Unknown Sources" in Settings → Security
2. Download the APK file
3. Open the APK file to install
4. Grant camera and storage permissions

Loading Bundles

1. Transfer .tncmp file to device via:
   • USB connection
   • Cloud storage (Dropbox, Google Drive)
   • File sharing apps
   • Email attachment
2. Remember the location (Downloads folder, etc.)
3. In app, tap "Load Bundle" and navigate to file

Taking Photos of Drawings

1. When creating a tone group, tap camera icon
2. Grant camera permission if prompted
3. Draw your tone pattern on paper
4. Hold phone steady and take photo
5. Make sure the drawing is clear and well-lit

Exporting Results

1. Tap export/download icon when finished
2. Results saved to device storage
3. Transfer back to researcher via:
   • USB connection
   • Cloud upload
   • File sharing
   • Email

4. Tone Matching Comparison

Purpose: Compare tone classifications from multiple speakers

User: Researcher

Input: Multiple result zip files (from different speakers)

Output: Comparison analysis

Step-by-Step Instructions

Step 1: Launch and Load Results

1. Open "Tone Matching Comparison"
2. Click "Load Result Files"
3. Select 2 or more result zip files (use Ctrl/Cmd+Click for multiple)
4. Click "Open"
5. Wait for analysis (usually a few seconds)

Step 2: Review Overall Statistics

The app displays:

• Total words: Number of words analyzed
• Full agreement: Words where all speakers agreed
• Disagreements: Words where speakers differed
• Agreement percentage: Overall consensus level

Step 3: Examine Disagreements

1. Scroll to "Disagreements" section
2. Table shows:
   • Word identifier (reference number or gloss)
   • Tone group assigned by each speaker
   • Whether disagreement is significant
3. For each disagreement, consider:
   • Do speakers need more instruction?
   • Is this dialectal variation?
   • Should this tone group be subdivided?
   • Does the word have contextual variation?

Step 4: Review Merged Groups

1. Scroll to "Merged Groups" section
2. Shows groups with >80% word overlap but different exemplars
3. Example:
   • Speaker 1: Group 3, exemplar "mountain"
   • Speaker 2: Group 7, exemplar "river"
   • 95% of words match
4. Decision: Which exemplar to use for final classification?

Step 5: Export Comparison Report

1. Click "Export Report" (if available)
2. Save as CSV or text file
3. Use for documentation and further analysis

Interpreting Results

Agreement Levels

• >90% agreement: Excellent - strong validation of tone groups
• 70-90% agreement: Good - investigate disagreements for insights
• 50-70% agreement: Moderate - may need clearer instructions or more training
• <50% agreement: Low - consider redesigning approach or working with more homogeneous data sets

Common Patterns

• High agreement overall with a few outliers: Normal - investigate the outliers specifically
• Consistent disagreement on certain words: May indicate phonological conditioning or free variation
• One speaker differs from all others: May need additional training or clarification

Complete Workflow Example

Next Steps

After completing your tone matching workflow:

• Update your Dekereke database with tone group assignments
• Use results for phonological analysis and orthography decisions
• Create additional bundles for other grammatical categories or syllable patterns
• Consider multi-dialect comparison using the same process

For more information, see:

• Getting Started Guide - Quick introduction
• FAQ - Common questions and troubleshooting
• GitHub Repository - Technical documentation