diff --git a/README.md b/README.md
index be873c4..c7c750e 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,107 @@
# bes-propres7-migrator
-A migrator from the `txt` songs (special markup format) to `ProPresenter7` `pro` format
+The `bes-propres7-migrator` is a utility designed to facilitate the conversion of song files from a custom `txt` format,
+using a special markup, to the `ProPresenter7` format (`.pro` files). This tool is particularly useful for those
+transitioning their song libraries to `ProPresenter7` and ensures a smooth conversion process.
-### Expected songs format
+## Features
+
+- **Simple Conversion**: Easily convert `.txt` song files to `.pro` format for `ProPresenter7`.
+- **Custom Configuration**: Flexible configuration options to suit your specific conversion needs.
+- **Advanced Sequencing with `BES` Sequence**: Automates song sequencing for efficient live presentation.
+- **Initial Setup Slide with `Macro` Reference**: Automates presentation environment setup for each song.
+
+## Installation
+
+To get started with `bes-propres7-migrator`, ensure you have Node.js installed on your machine. Clone this repository
+and run `npm install` to install all dependencies.
+
+```bash
+git clone https://github.com/your-repo/bes-propres7-migrator.git
+cd bes-propres7-migrator
+npm install
+```
+
+## Usage
+
+### Expected Song Format
+
+Your .txt song files should follow this specific markup format for successful conversion:
```
[title]
-Aceasta mi-e dorința să Te onorez
+Your Song Title
[sequence]
1,c,2,c
[1]
-Aceasta mi-e dorința, să Te onorez,
+Verse 1 lyrics here...
+
+[chorus]
+Chorus lyrics here...
+
+[2]
+Verse 2 lyrics here...
+
+```
+
+#### Example (romanian song):
+
+```
+[title]
+Aceasta mi-e dorința, să Te-onorez {alternative: {_}, composer: {_}, writer: {_}, arranger: {_}, interpreter: {_}, band: {_}, key: {_}, tempo: {_}, tags: {_}, version: {_}, genre: {\*}, rcId: {59763}, id: {8ipLZddXG3Zy7Hbbo93Vm7}, contentHash: {418384}}
+
+[sequence]
+v1,c,v2,c
+
+[v1]
+Aceasta mi-e dorința, să Te-onorez,
Cu ființa-ntreagă să Te slăvesc.
Te ador, Stăpâne, și mă închin,
Lauda și onoarea Ți se cuvin!
-[chorus]
+[c]
Ție-Ți dau inima și sufletul meu,
Pentru Tine vreau să trăiesc!
Domnul meu, Te iubesc!
Zi de zi vreau să-mplinesc
Doar sfântă voia Ta!
-[2]
+[v2]
Vrednic ești de cinste, fii lăudat!
Împărat al slavei, fii înălțat!
Alfa și Omega, de-a pururi viu,
Domn al veșniciei, în veci! Amin!
+
```
-### How to run?
+### Running the Migrator
-- Assuming that the following config is fine:
+1. Set up your environment variables according to your local setup:
```dotenv
-LOCAL_SOURCE_DIR=directory-with-txt-songs
-LOCAL_OUT_DIR=directory-with-pro-songs
+# .env.local
+LOCAL_SOURCE_DIR=src-directory-with-txt-songs
+LOCAL_OUT_DIR=out-directory-with-pro-songs
```
-Simply run the `npm run convert:local`
-
-### How to customize the runner
-
-- Pass the following env variables with your source and out directories
+2. To convert your songs, execute the following command:
-```dotenv
-LOCAL_SOURCE_DIR=directory-with-txt-songs
-LOCAL_OUT_DIR=directory-with-pro-songs
+```bash
+npm run convert:local
```
-- Use the `convertSongsToPP7FormatLocally` method to do the conversion as follows:
+### Customization Options
+
+You can customize the conversion process by adjusting the environment variables or by directly using
+the `convertSongsToPP7FormatLocally` method with your own configurations:
```typescript
import dotenv from 'dotenv';
-import { Config, convertSongsToPP7FormatLocally } from './';
+import { convertSongsToPP7FormatLocally } from './';
import { Presentation_CCLI } from './proto/presentation';
-import { Graphics_Text_Attributes_Font } from './proto/graphicsData';
+import { Font } from './proto/graphicsData';
dotenv.config();
@@ -75,7 +119,7 @@ const CONFIG = {
size: 58,
family: 'CMGSans',
bold: true,
- } as Graphics_Text_Attributes_Font,
+ } as Font,
graphicSize: {
width: 1920,
height: 1080,
@@ -94,16 +138,91 @@ convertSongsToPP7FormatLocally({
});
```
-### How this repo works
+### The ProPresenter7 outcome
+
+
+
+### How It Works
-This repo is doing a reverse engineering from the pro presenter protobuf format to a known format, and then it encodes
-back presentation files by using the https://github.com/arkadiyt/protodump utility.
+The `bes-propres7-migrator` leverages reverse engineering of the `ProPresenter` `protobuf` format through
+the `protodump`
+utility for encoding and decoding presentation files. To utilize this:
-To use that, simply run the following commands:
-`git clone https://github.com/arkadiyt/protodump.git`
-`go build -o protodump cmd/protodump/main.go`
+```bash
+git clone https://github.com/arkadiyt/protodump.git
+go build -o protodump cmd/protodump/main.go
+```
-#### Find proto files from PP7
+### Advanced Sequencing with BES Sequence
+
+A standout feature of the `bes-propres7-migrator` is its ability to intelligently create BES sequences in ProPresenter7,
+enhancing the presentation of songs during live events. This section explains how the BES sequence works and the
+advantages it offers.
+
+#### How BES Sequence Works
+
+When converting songs, `the bes-propres7-migrator` not only transfers the lyrics and formatting but also smartly
+organizes
+song sections into an efficient sequence for live presentation. Given a song with the sequence (1,c,2,c), the migrator
+constructs what is referred to as a BES sequence in ProPresenter7.
+
+This BES sequence strategically references the chorus (c) only once in the `ProPresenter7` sequence setup, even though
+it
+appears twice in the song's progression. This approach results in a sequence where the chorus is prepared to be
+displayed each time it's needed, without requiring multiple entries in the sequence.
+
+#### Benefits of BES Sequence
+
+- Simplicity in Navigation: Operators can advance through the song by simply pressing the forward key, without needing
+ to
+ remember the song's order or manually navigate back to the chorus. This is especially useful in live settings where
+ attention and timing are critical.
+- Efficiency in Presentation: Reduces the clutter and complexity of the song's visual presentation, making it easier for
+ the audience to follow along.
+- Optimized Performance: Minimizes the cognitive load on the person controlling the presentation, allowing them to focus
+ more on the event's flow and less on the technical aspects of the presentation software.
+- Implementation
+ When utilizing the `convertSongsToPP7FormatLocally` method, the migrator automatically analyzes the song's sequence
+ and
+ applies the BES sequence logic. There's no need for manual setup or additional configuration to enable this feature.
+ This automated process ensures your songs are ready for efficient and effective presentation with minimal effort on
+ your
+ part.
+
+#### Example
+
+For a song with a specified sequence of (1,c,2,c), the migrator creates a sequence in `ProPresenter7` that smartly
+incorporates the chorus to appear at the correct intervals, optimizing both the operator's experience and the audience's
+engagement.
+
+### Initial Setup Slide with Macro Reference
+
+An innovative feature of the `bes-propres7-migrator` is the automatic inclusion of an initial setup slide in every
+exported file. This first slide is intentionally left empty and contains a reference to a predefined macro. The purpose
+of this slide is to facilitate the seamless preparation of the presentation environment before the actual song content
+is displayed.
+
+#### Purpose and Benefits
+
+- Environment Preparation: The macro referenced in the first slide is designed to automate the setup process for your live
+ event presentation. This includes clearing previous settings, configuring the appropriate audience and stage layouts,
+ setting clocks, backgrounds, and other necessary adjustments.
+- Efficiency and Consistency: By automating the setup process, this feature ensures that all songs start with a consistent
+ environment, reducing manual setup errors and saving time during live events.
+- Seamless Transition into Content: Since every song starts from the second slide, the initial setup slide ensures that
+ all preliminary adjustments are made without displaying unnecessary content to the audience, leading to a smoother
+ transition and a more professional presentation.
+
+- #### How to Use
+ The initial setup slide is included automatically with every song conversion. To customize the actions performed by the
+ referenced macro, you may need to edit the macro settings within ProPresenter7 according to your event's specific
+ requirements. This customization allows you to tailor the environment setup process to match the unique needs of your
+ presentation.
+
+
+📖 How to regenerate the `.proto` files when a new version of `ProPresenter7` arrives.
+
+### Step 1: Find `.proto` files from `ProPresenter7`
> Assuming that `protodump` is a sibling of this dir:
@@ -111,7 +230,7 @@ To use that, simply run the following commands:
find /Applications/ProPresenter.app/ -type f -perm +111 -print -exec ../protodump/protodump -file {} -output ./proto \;
```
-#### Decode proto files to TS
+#### Decode `ProPresenter7` `.proto` files to `.ts`
```unix
cd proto
@@ -119,6 +238,11 @@ cd proto
for f in ./*; do protoc --plugin=../node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./ --ts_proto_opt=esModuleInterop=true ./$f ; done
```
+
+
+
+📖 How to decode a single `.pro` presentation files for debugging purposes..
+
#### Decode a single presentation file called `TEMP.pro` to `TS`
```unix
@@ -132,5 +256,7 @@ protoc --decode rv.data.Presentation ./presentation.proto < ~/Documents/ProPrese
```unix
cd proto
-protoc --decode rv.data.Presentation ./presentation.proto < ../win-debug/TEST_TEMPLATE_3.pro > ../win-debug/TEST_TEMPLATE_3.txt
+protoc --decode rv.data.Presentation ./presentation.proto < ../windows-templates/TEST_TEMPLATE_3.pro > ../windows-templates/TEST_TEMPLATE_3.txt
```
+
+
diff --git a/outcome_pp7.png b/outcome_pp7.png
new file mode 100644
index 0000000..b531121
Binary files /dev/null and b/outcome_pp7.png differ
diff --git a/package.json b/package.json
index da48485..ffa7536 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
- "name": "migrator_propres7-node",
+ "name": "bes-propres7-migrator",
"version": "1.0.0",
- "description": "A converter from .txt song lyrics to PP7 pro format.",
+ "description": "A converter from .txt song lyrics to ProPresenter7 .pro format.",
"main": "index.ts",
"scripts": {
"test:ci": "NODE_ENV=test TZ='Europe/Bucharest' jest --runInBand --no-cache",
diff --git a/runner.ts b/runner.ts
index 6a75a3c..42e6ab5 100644
--- a/runner.ts
+++ b/runner.ts
@@ -5,11 +5,11 @@ import {
convertSongsToPP7FormatRemotely,
} from './';
import { Presentation_CCLI } from './proto/presentation';
-import { Graphics_Text_Attributes_Font } from './proto/graphicsData';
+import { Font } from './proto/font';
dotenv.config();
-const CONFIG = {
+const BES_CONFIG = {
arrangementName: 'BES',
ccliSettings: {
publisher: 'Biserica Emanuel Sibiu',
@@ -24,7 +24,7 @@ const CONFIG = {
bold: true,
family: 'CMG Sans Cn CAPS',
face: 'Bold',
- } as Graphics_Text_Attributes_Font,
+ } as Font,
graphicSize: {
width: 1920,
height: 1080,
@@ -38,7 +38,7 @@ const CONFIG = {
const deploymentArgs = {
sourceDir: process.env.LOCAL_SOURCE_DIR as string,
baseLocalDir: process.env.LOCAL_OUT_DIR as string,
- config: CONFIG,
+ config: BES_CONFIG,
};
if (process.env.CONNECT_TO_G_DRIVE !== 'true') {
diff --git a/win-debug/TEST_TEMPLATE_1.pro b/windows-templates/TEST_TEMPLATE_1.pro
similarity index 100%
rename from win-debug/TEST_TEMPLATE_1.pro
rename to windows-templates/TEST_TEMPLATE_1.pro
diff --git a/win-debug/TEST_TEMPLATE_1.txt b/windows-templates/TEST_TEMPLATE_1.txt
similarity index 100%
rename from win-debug/TEST_TEMPLATE_1.txt
rename to windows-templates/TEST_TEMPLATE_1.txt
diff --git a/win-debug/TEST_TEMPLATE_2.pro b/windows-templates/TEST_TEMPLATE_2.pro
similarity index 100%
rename from win-debug/TEST_TEMPLATE_2.pro
rename to windows-templates/TEST_TEMPLATE_2.pro
diff --git a/win-debug/TEST_TEMPLATE_2.txt b/windows-templates/TEST_TEMPLATE_2.txt
similarity index 100%
rename from win-debug/TEST_TEMPLATE_2.txt
rename to windows-templates/TEST_TEMPLATE_2.txt
diff --git a/win-debug/TEST_TEMPLATE_3.pro b/windows-templates/TEST_TEMPLATE_3.pro
similarity index 100%
rename from win-debug/TEST_TEMPLATE_3.pro
rename to windows-templates/TEST_TEMPLATE_3.pro
diff --git a/win-debug/TEST_TEMPLATE_3.txt b/windows-templates/TEST_TEMPLATE_3.txt
similarity index 100%
rename from win-debug/TEST_TEMPLATE_3.txt
rename to windows-templates/TEST_TEMPLATE_3.txt