Metadata-Version: 2.4
Name: ChurchSong
Version: 0.7.0
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: openpyxl>=3.1.5
Requires-Dist: platformdirs>=4.3.6
Requires-Dist: polib>=1.2.0
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
Requires-Dist: rich>=14.0.0
Requires-Dist: textual>=3.0.1

# 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
configured.

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

Finally, you can create song usage statistics in various output formats for chosen
time periods.

## 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 via `uv` 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 manual 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) to use an interactive menu where you can select the desired
parts to download (default is all) and then execute the agenda download.

Or you can bypass the interactive menu and 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, a `Schedule.col` for SongBeamer is created 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`.

Only the default arrangements of the songs are verified, unless you also specify
`--all_arrangements` in which case all arrangements are checked for.

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.

### Song usage statistics

If you are interested in how many times what song has been performed in a specific
year or in specific years, you can use `songs usage` to create output in various
formats (currently supporting `text`, `html`, `json`, `csv`, `latex`, `mediawiki`, and
`xlsx`) by specifying the format with `--format`.

Output format `xlsx` requires to specify an output file using `--output`. This is
optional for all other output formats.

The time period for the statistics can be specified using either `YYYY`, `-YYYY`,
`YYYY-`, or `YYYY-YYYY`.
