Metadata-Version: 2.2
Name: ChurchSong
Version: 0.5.5
Summary: Download the event agenda from ChurchTool and instantiate a PowerPoint slide template with the names and portraits of service staff.
Author: Stefan Bellon
License: MIT License
        
        Copyright (c) 2024 Stefan Bellon
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/sbellon/ChurchSong
Project-URL: Repository, https://github.com/sbellon/ChurchSong.git
Project-URL: Changelog, https://github.com/sbellon/ChurchSong/blob/master/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: alive-progress>=3.2.0
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: prettytable>=3.12.0
Requires-Dist: psutil>=6.1.0; sys_platform == "win32"
Requires-Dist: pydantic>=2.9.2
Requires-Dist: python-pptx>=1.0.2
Requires-Dist: requests>=2.32.3

# ChurchSong

## Introduction

The main purpose of this tool is to download the event agenda from ChurchTool as well
as the names of the service staff, preparing a PowerPoint slide with the names and
portraits to be presented at the beginning of the event.

Additionally, the SongBeamer agenda can be modified by placing slides at the opening
or closing, or after specific keywords. Colors of the SongBeamer captions can also be
changed.

The ChurchTools song database can also be checked for consistency regarding metadata
as well as present .sng files to contain a background image.

## Prerequisites

Python package manager [uv](https://docs.astral.sh/uv/) must be installed and
accessible via PATH. Easiest way is to follow the steps listed as
[Standalone Installer](https://docs.astral.sh/uv/getting-started/installation/).

## Installation

Simply install ChurchSong by executing `uv install ChurchSong`. Tool `ChurchSong` is
then available from the command line.

You may place the files `ChurchSong.bat` and `ChurchSong.ico` from the `resources`
folder somewhere for convenience as you can just double-click it to load the upcoming
agenda and start SongBeamer.

## Configuration

### Config file

You need to copy the `resources/config.toml.example` to
`%LOCALAPPDATA%\ChurchSong\config.toml` and adjust the content accordingly.

### PowerPoint template

You need to prepare a PowerPoint template with a slide master which contains
placeholders for pictures and names for the team members. The ChurchTool's service
team name has to be put at the PowerPoint base placeholder via the Select Pane
(Alt-F10).

## Usage

### SongBeamer agenda download

To download the upcoming agenda you can just execute `ChurchSong` without any
switches (e.g. double-click it). To specify a starting date to look for the next event,
you can specify additional command line arguments `agenda FROM_DATE` as positional
parameter with `FROM_DATE` in the form `YYYY-MM-DD`.

If everything goes well, the agenda is downloaded into the `temp_dir`, the slide is
created from the template, SongBeamer's `Schedule.col` is adjusted and finally
SongBeamer itself is launched with the prepared `Schedule.col`.

You can keep the `temp_dir` as is (it is added to and overwritten in future
invocations), but there is also no harm in deleting the `temp_dir` as it is
automatically re-created.

### ChurchTools song verification

With the additional command `songs verify` you can check the songs in the
ChurchTools song database for specific properties like CCLI number, song name, tags,
arrangement source, duration and a SongBeamer `.sng` file with the `#BackgroundImage`
property set.

With optional positional argument `FROM_DATE` in the form `YYYY-MM-DD` you can select
to only check the songs of the next event agenda after `FROM_DATE`.

Using command options `--exclude_tags` and/or `--include_tags` you can filter out
songs with specific tags or only include songs with specific tags in the check.
