ProPresenter Lyrics Export

Logo

Extract and export worship song lyrics from ProPresenter 7

View the Project on GitHub adamswbrown/propresenterlyricexport

Developer Guide

← Back to Home

Information for developers and contributors.

For Developers Contributing Code

Quick Start for Contributors

# 1. Clone and install
git clone https://github.com/adamswbrown/propresenterlyricexport.git
cd propresenterlyricexport
npm install

# 2. Run development version
npm start -- status

# 3. Run tests
npm test

# 4. Build for distribution
npm run build
npm run build:exe
npm run electron:dev

Technology Stack

Key Concepts

Shared Core Architecture

The project uses a shared core + dual distribution pattern:

src/                          (Shared core - both paths use this)
├── propresenter-client.ts    (API wrapper)
├── lyrics-extractor.ts       (Lyric parsing)
└── pptx-exporter.ts          (PowerPoint generation)

electron/                     (Desktop app only)
└── main/index.ts             (Electron main process)

src/cli.ts                    (CLI only)
└── Command-line interface

Changes to src/ affect both CLI and desktop app. UI changes stay isolated.

Critical Issues

⚠️ pptxgenjs Locked at 3.10.0 - Never upgrade without resolving bundling issues. Versions 3.11.0+ fail in CLI executables due to dynamic fs imports.

Directory Structure

src/
├── cli.ts                         # CLI entry point
├── propresenter-client.ts         # ProPresenter API wrapper
├── lyrics-extractor.ts            # Lyric parsing logic
├── pptx-exporter.ts               # PowerPoint generation
├── services/                      # Reusable business logic
│   ├── playlist-exporter.ts
│   ├── song-matcher.ts
│   ├── bible-fetcher.ts
│   └── ...
├── types/                         # TypeScript interfaces
│   ├── playlist.ts
│   ├── service-order.ts
│   └── ...
└── utils/                         # Pure utility functions

electron/
├── main/index.ts                  # Main process, IPC handlers
├── preload/index.ts               # Preload script
└── renderer/src/
    ├── App.tsx                    # React app root
    ├── ServiceGeneratorView.tsx   # Service Generator component
    └── ...

dist/                              # Compiled CLI (generated)
dist-electron/                     # Compiled Electron (generated)
executables/                       # CLI executables (generated)
release/                           # Packaged Electron app (generated)

Files to Study

Core Logic:

Services:

Desktop App:

Electron Integration:

Common Development Tasks

Running the Application

Development mode:

npm start -- status        # CLI
npm run electron:dev       # Desktop app

Production build:

npm run build              # Compile TypeScript
npm run build:exe          # Create executables
npm run electron:package   # Package app

Making Changes

If editing src/ (core logic):

  1. Test both CLI path and Electron path
  2. Run: npm run build && npm start -- status
  3. Also test: npm run electron:dev

If editing Electron UI:

  1. Changes hot-reload automatically
  2. Run: npm run electron:dev
  3. Test in desktop app

If editing CLI:

  1. Test directly: npm start -- [command]
  2. After changes: npm run build

Running Tests

npm test                   # Run test suite
npm test -- --watch       # Watch mode
npm run coverage          # Coverage report

Committing Code

# Make your changes
git add src/...

# Commit with descriptive message
git commit -m "feat: Add feature description

- Detailed change 1
- Detailed change 2"

# Follow conventions in CONTRIBUTING.md

Next Steps

Choose what you want to explore:

Getting Help