Metadata-Version: 2.2
Name: ChurchSong
Version: 0.5.15
Summary: Download the event agenda from ChurchTool and instantiate a PowerPoint slide template with the names and portraits of service staff as well as song database verification.
Author: Stefan Bellon
License: MIT License
        
        Copyright (c) 2024-2025 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/main/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.

## Installation

### Automatic installation

A simple installation method (including a generic configuration template that you still
have to configure for your needs) is to execute the following in a `cmd.exe` shell:

```
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/sbellon/ChurchSong/refs/heads/main/resources/install.ps1 | iex"
```

A shortcut will be installed on the desktop and command `ChurchSong` will be available
from the command line.

### Manual installation

If you do not want to use this method, you will have to do a manual install.

The recommendation is to use Python package manager [uv](https://docs.astral.sh/uv/)
which you have to install first and make it accessible via PATH. This can be done by
following the steps listed at
[Standalone Installer](https://docs.astral.sh/uv/getting-started/installation/).

Afterwards you have to execute `uv install ChurchSong` to install ChurchSong itself.

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

Command `ChurchSong` will be available from the command line afterwards.

### Updating

Once installed you can update to the latest release version by executing
`ChurchSong self update` from the command line.

## Configuration

### Config file

You can check the location of your configuration files by executing
`ChurchSong self info` from the command line. Typically, on Windows, the location of
the configuration file will be `%LOCALAPPDATA%\ChurchSong\config.toml`.

You need to adjust the content of `%LOCALAPPDATA%\ChurchSong\config.toml` for your
needs (at least `base_url` and `login_token`).

If you used the simple installation method above, the template was copied there for
you, if you did a manuall install you have to copy `resources/config.toml.example`
there for yourself.

### 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) or use the command `agenda`. 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 an ISO date format
(e.g., `YYYY-MM-DD`, `YYYY-MM-DDT10:00:00`, or `YYYY-MM-DDT10:00:00+01:00`).

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 family `songs verify` you can check the songs for specific
properties like CCLI number, song name, tags, arrangement source, duration and a
SongBeamer `.sng` file with the `#BackgroundImage` property set.

Without any further argument, `songs verify` checks the songs for the next agenda that
would appear when just using `agenda` command.

With `songs verify FROM_DATE` you can select to only check the songs of the next event
agenda after `FROM_DATE` (like `agenda FROM_DATE`, `FROM_DATE` can be an ISO date
format, e.g., `YYYY-MM-DD`, `YYYY-MM-DDT10:00:00`, or `YYYY-MM-DDT10:00:00+01:00`).

You can check the whole ChurchTools songs database by using `songs verify --all`.

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