Command Line Interface Reference

The slidemovie command is the primary entry point for all operations.

Basic Syntax

slidemovie [PROJECT_NAME] [OPTIONS]

Positional Arguments

  • PROJECT_NAME (Required)
    • The identifier for your project.
    • The tool looks for {PROJECT_NAME}.md in the source directory.
    • If using Subproject Mode (--sub), this argument specifies the Parent directory name (used for output categorization).

Options

Mode Flags (At least one is required)

  • -p, --pptx
    • Action: Converts the source Markdown file into a PowerPoint (.pptx) file.
    • Use Case: Initial draft creation or updating slide text.
    • Note: This overwrites existing PPTX files in the source directory unless configured otherwise.
  • -v, --video
    • Action: Builds the complete video.
    • Steps:
      1. Generates Audio (TTS) from Markdown notes.
      2. Exports Images from the PPTX file (or from the PDF file when --pdf is set).
      3. Combines Audio and Images into slide clips.
      4. Concatenates clips into the final movie.
    • Use Case: Final production.
    • Note: Slide images are normalized to screen_size. If the source aspect ratio differs, the image is scaled to fit and padded evenly (letterbox/pillarbox) with image_pad_color.
  • --pdf
    • Action: Uses a PDF file ({PROJECT_NAME}.pdf) as the image source instead of the PowerPoint file.
    • Use Case: When slides are already available as a PDF (e.g., exported from another tool). Combine with -v to build the video directly from the PDF.
    • Note: Only affects image generation during --video; it has no effect on --pptx (-p) drafting. Audio generation from Markdown notes is unchanged.

Path & Structure

  • -s DIR, --source-dir DIR
    • Default: . (Current directory)
    • Description: The directory containing your source Markdown and PPTX files.
    • Example: slidemovie myproject -s ./docs (Looks for ./docs/myproject.md)
  • --sub SUB_NAME
    • Description: Enables Hierarchical (Subproject) Mode.
    • Behavior:
      • PROJECT_NAME is used for the output parent folder.
      • SUB_NAME becomes the Child folder (Subproject).
      • Input Source: {Child}/{Child}.md
      • Output Video: movie/{Parent}/{Child}/{Child}.mp4
    • Example: slidemovie Season1 --sub Episode1
  • -o DIR, --output-root DIR
    • Default: ./movie (relative to the source directory)
    • Description: Specifies a custom root directory for all generated video artifacts.
    • Note: This can also be configured via output_root in config.json. If the specified directory does not exist, an error will occur if output_root is explicitly set. If it is not set, the default directory will be created automatically.
  • -f NAME, --filename NAME
    • Default: Same as the project ID.
    • Description: Specifies the filename of the final .mp4 video (without extension).

TTS Overrides (Temporary)

These options override settings defined in config.json for the current run only.

  • --tts-provider NAME: e.g., google, openai, azure, voicevox.
  • --tts-model NAME: e.g., gpt-4o-mini-tts, gemini-3.1-flash-tts-preview (not used by azure/voicevox).
  • --tts-voice NAME: e.g., cedar, charon. For voicevox, an integer speaker style ID (e.g., 3).
  • --tts-voicevox-url URL: VOICEVOX engine URL (default http://127.0.0.1:50021). Only used with --tts-provider voicevox.
  • --prompt TEXT: Overrides the system prompt and enables prompt usage (tts_use_prompt=True).
  • --no-prompt: Disables the use of a system prompt (tts_use_prompt=False).
  • --prompt-separator STR: Separator inserted between the style prompt and the spoken text, e.g. "\n\n## Script\n" (see Separating the prompt from the script). Empty by default.
  • --chunk-size N: Max characters per TTS chunk. Setting this enables automatic splitting of long narration (see Long narration).
  • --split-chars STR: Candidate split characters for chunking (default: 。．.!！?？ and newline).
  • --chunk-overflow {extend,error}: Behavior when no split candidate is found within --chunk-size. extend reads on to the next candidate; error stops with an error.

Debugging

  • --debug
    • Enables detailed logging (INFO/DEBUG level).
    • Shows skipped tasks and internal processing details.
    • Sets FFmpeg log level to info.

Examples

1. Basic draft generation:

slidemovie tutorial -p

2. Building a video in a specific folder:

slidemovie tutorial -s ./content -v

3. Building a subproject with OpenAI TTS:

slidemovie Course101 --sub Lesson01 -v --tts-provider openai --tts-model gpt-4o-mini-tts --no-prompt --tts-voice alloy

4. Building with VOICEVOX (local engine, must be running):

slidemovie tutorial -v --tts-provider voicevox --tts-voice 3 --no-prompt