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).

    When -g / --gui is supplied, PROJECT_NAME is optional because it can be entered in the GUI.

Options

GUI

  • -g, --gui
    • Action: Opens the Tkinter graphical interface instead of starting a build from the command line.
    • Behavior: PROJECT_NAME, mode flags, paths, and TTS options supplied on the command line become initial GUI values. The build starts only after you select an action and click Run in the GUI.
    • Requirements: Tkinter must be available in the Python installation. The GUI supports standard and subproject layouts, PPTX or PDF image sources, and temporary TTS overrides.

Mode Flags (At least one is required unless --gui is used)

  • -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