| 1 | # Troubleshooting |
| 2 | |
| 3 | ## Validation Failed |
| 4 | |
| 5 | 1. Run: |
| 6 | |
| 7 | ```bash |
| 8 | python3 scripts/project_manager.py validate <project_path> |
| 9 | ``` |
| 10 | |
| 11 | 2. Fix missing files or invalid directories reported by the validator. |
| 12 | 3. Re-run validation before post-processing or export. |
| 13 | |
| 14 | ## SVG Preview Looks Wrong |
| 15 | |
| 16 | 1. Check the file path and filename. |
| 17 | 2. Confirm naming conventions are consistent. |
| 18 | 3. Run the mandatory post-processing step when you need a self-contained preview: |
| 19 | |
| 20 | ```bash |
| 21 | python3 scripts/finalize_svg.py <project_path> |
| 22 | python3 -m http.server --directory <project_path>/svg_final 8000 |
| 23 | ``` |
| 24 | |
| 25 | `svg_final/` is the visual-preview artifact and may be inserted into PowerPoint as an SVG picture. Fix authored content in `svg_output/`, then regenerate `svg_final/`; do not edit the derived preview as the source. |
| 26 | |
| 27 | ## Speaker Notes Do Not Split |
| 28 | |
| 29 | Check `total.md`: |
| 30 | - headings must start with `# ` |
| 31 | - heading text must match SVG filenames |
| 32 | - sections must be separated by `---` |
| 33 | |
| 34 | Then rerun: |
| 35 | |
| 36 | ```bash |
| 37 | python3 scripts/total_md_split.py <project_path> |
| 38 | ``` |
| 39 | |
| 40 | ## PPT Export Quality Issues |
| 41 | |
| 42 | Preferred sequence: |
| 43 | |
| 44 | ```bash |
| 45 | python3 scripts/total_md_split.py <project_path> |
| 46 | python3 scripts/finalize_svg.py <project_path> |
| 47 | python3 scripts/svg_to_pptx.py <project_path> |
| 48 | ``` |
| 49 | |
| 50 | Keep all three steps even though they have different consumers: Step 7.2 creates the mandatory `svg_final/` visual preview, while the supported native PPTX exporter reads `svg_output/` directly. Do not pass `-s final` for a release export; that override is diagnostic-only. |
| 51 | |
| 52 | ## Inserted SVG Does Not Convert Cleanly to Shapes |
| 53 | |
| 54 | PowerPoint's manual Convert-to-Shape behavior is unsupported. `svg_final/` is supported only as a visual preview / SVG picture. Use the native PPTX generated from `svg_output/` when editable DrawingML shapes are required. |
| 55 | |
| 56 | ## Recorded Narration Missing |
| 57 | |
| 58 | 1. Generate audio after `total_md_split.py`, so filenames in `audio/` can match split `notes/*.md` files. |
| 59 | 2. Export with the project-relative audio directory: |
| 60 | |
| 61 | ```bash |
| 62 | python3 scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeural |
| 63 | python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio |
| 64 | ``` |
| 65 | |
| 66 | `--recorded-narration` prepares PowerPoint recorded timings and narrations. If it fails, check: |
| 67 | - every slide has a matching `m4a`, `mp3`, or `wav` file in `audio/` |
| 68 | - `ffprobe` is installed and can read each audio duration |
| 69 | - the deck is not using `--animation-trigger on-click` |
| 70 | |
| 71 | Use `--narration-audio-dir audio` only when you intentionally want lower-level, partial audio embedding instead of PowerPoint recorded timings. |
| 72 | |
| 73 | ## Dependency Checklist |
| 74 | |
| 75 | Most tools use the standard library. Install extra dependencies only when needed: |
| 76 | |
| 77 | ```bash |
| 78 | pip install -r requirements.txt |
| 79 | ``` |
| 80 | |
| 81 | Important optional packages: |
| 82 | - `python-pptx` for PPTX export |
| 83 | - `edge-tts` for `notes_to_audio.py` recorded narration audio |
| 84 | - `Pillow` for image utilities |
| 85 | - `numpy` for watermark removal |
| 86 | - `PyMuPDF` for PDF conversion |
| 87 | - `google-genai` for Gemini image generation |
| 88 |