FreeShow Web Tools

A guarded, browser-based editor for organizing FreeShow projects and slides from another device. It is designed for teams that operate FreeShow on a Mac but want a focused web interface for preparing a service or presentation.

Important

This is an independent community project. It is not affiliated with, endorsed by, or maintained by the FreeShow project.

Features

• Browse live FreeShow projects and reorder shows, sections, and media.
• Open a show as a slide-card workspace, reorder grouped slides, and remove slides.
• Upload a photo or add an existing searched image as a full-slide image.
• Create scripture shows from Bibles already installed in FreeShow.
• Find native .show files and add them to the selected project.
• Convert ProPresenter 7 .pro files with an explicitly configured FreeShow song template.
• Back up project and show data before every mutation.
• Reject stale browser edits with live and file revision checks.
• Verify mutations in the running FreeShow application before persisting them.

Compatibility

The initial release is alpha software and has been tested with:

• macOS
• FreeShow 1.6.4
• Python 3.9+
• ProPresenter 7 .pro files for the optional conversion feature

FreeShow's internal data and API formats can change. Back up your FreeShow data and validate a new FreeShow version with copied or exported content before using this tool on a production library.

Requirements

• FreeShow installed in /Applications and running under your macOS account.
• FreeShow's local API enabled on port 5506.
• Python 3.9 or newer.
• macOS Remote Login enabled. The installer uses a localhost-only, forced-command SSH key so the background web service can access the same privacy-managed folders as your account.

Quick start

git clone https://github.com/MichaelDarkBlue/FreeShowWebTools.git
cd FreeShowWebTools
chmod +x scripts/*.sh
./scripts/install-macos.sh

Open http://127.0.0.1:8787 on the FreeShow Mac.

The default installation searches only your Documents and Downloads folders and listens only on localhost. See Configuration to enable access from another trusted device or ProPresenter conversion.

Configuration

Set variables in the shell before running scripts/install-macos.sh. The installer stores non-secret values in the per-user LaunchAgent and worker configuration.

Variable	Default	Purpose
FSWT_TARGET_HOME	Current home	Account that owns FreeShow content
FSWT_SEARCH_ROOTS	Documents and Downloads	Colon-separated allowed roots
FSWT_BIND_HOST	127.0.0.1	Web listener address
FSWT_PORT	8787	Web listener port
FSWT_SONG_TEMPLATE_ID	Empty	Template ID for .pro conversion
FSWT_SONG_TEMPLATE_NAME	Empty	Exact matching template name

For example:

export FSWT_BIND_HOST="100.x.y.z"  # this Mac's Tailscale address
export FSWT_SONG_TEMPLATE_ID="your-template-id"
export FSWT_SONG_TEMPLATE_NAME="Your Song Template"
./scripts/install-macos.sh

The application has no user login. Never bind it to a public or untrusted network. A private Tailscale address with suitable ACLs is the intended remote access model.

To configure conversion, find the desired template entry in FreeShow's Config/templates.json and copy both its object key (the ID) and exact name. Conversion remains disabled with a clear error until both values are set.

More detail is available in docs/configuration.md.

Safety model

The browser never receives complete project stores, Bible contents, or native show files. Mutation requests contain IDs, revisions, and permutations. The worker then:

1. validates all input and allowed paths;
2. reloads live state and rejects stale revisions;
3. creates a timestamped backup;
4. performs and verifies the live FreeShow change;
5. atomically persists the verified native data; and
6. attempts rollback if verification or persistence fails.

The localhost SSH key is restricted by source address, OpenSSH restrict, and a forced freeshow_web_tools.worker command. It cannot request an interactive shell.

Updating

git pull --ff-only
./scripts/install-macos.sh

Review release notes before updating FreeShow itself.

Uninstalling

./scripts/uninstall-macos.sh

The uninstaller removes the LaunchAgent, forced worker authorization, shared worker copy, and restart helper. It leaves the repository, logs, backups, and FreeShow data in place.

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONPATH=src python3 -m freeshow_web_tools.app

The runtime uses only Python's standard library. See CONTRIBUTING.md and docs/architecture.md for the project structure and invariants.

Support and security

• Usage questions: SUPPORT.md
• Vulnerability reports: SECURITY.md
• Bugs and feature requests: GitHub Issues

License

FreeShow Web Tools is available under the MIT License.