diff --git a/README.md b/README.md
index c7c750e..e651ea7 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,9 @@ To get started with `bes-propres7-migrator`, ensure you have Node.js installed o
and run `npm install` to install all dependencies.
```bash
-git clone https://github.com/your-repo/bes-propres7-migrator.git
+git clone https://github.com/ilucut/bes-propres7-migrator.git
cd bes-propres7-migrator
+
npm install
```
@@ -76,22 +77,99 @@ Domn al veșniciei, în veci! Amin!
```
-### Running the Migrator
+### Running the Migrator locally
+
+You can migrate your songs locally by following these steps:
1. Set up your environment variables according to your local setup:
```dotenv
# .env.local
-LOCAL_SOURCE_DIR=src-directory-with-txt-songs
-LOCAL_OUT_DIR=out-directory-with-pro-songs
+TZ=Europe/Bucharest
+# src-directory-with-txt-songs
+LOCAL_SOURCE_DIR=../bes-lyrics/verified
+# out-directory-with-pro-songs
+LOCAL_OUT_DIR=./out_temp_for_local
+CONNECT_TO_G_DRIVE=false
+
```
-2. To convert your songs, execute the following command:
+2. To convert your songs locally, execute the following command:
```bash
npm run convert:local
```
+As a result, the migrator will convert all `.txt` song files from the specified source directory to `.pro` format in the
+given directory, with the following format:
+
+Under the `./out_temp_for_local`, and a dynamically created directory like `/2024-04-09-17:18:05`,
+the `Aceasta mi-e dorinta sa Te-onorez.pro` will be generated.
+Also, a `manifest.json` will be generated like e.g.:
+
+```json
+{
+ "inventory": [
+ {
+ "id": "8ipLZddXG3Zy7Hbbo93Vm7",
+ "fileName": "Aceasta mi-e dorinta sa Te-onorez.txt",
+ "contentHash": "418384"
+ }
+ ],
+ "updatedOn": "2024-04-09-17:18:05"
+}
+```
+
+### Running the Migrator remotely
+
+You can migrate your songs remotely to a Google Drive account by following these steps:
+
+1. Set up your environment variables according to your local setup:
+
+```dotenv
+# .env.remote
+TZ=Europe/Bucharest
+# src-directory-with-txt-songs
+LOCAL_SOURCE_DIR=../bes-lyrics/verified
+GDRIVE_ROOT_FOLDER_ID=id-of-your-folder-in-gdrive
+CONNECT_TO_G_DRIVE=true
+GDRIVE_BES_CLIENT_ID=taken-from-the-gdrive-app-config
+GDRIVE_BES_CLIENT_SECRET=taken-from-the-gdrive-app-config
+GDRIVE_BES_CLIENT_REFRESH_TOKEN=taken-from-the-gdrive-app-config
+```
+
+2. To convert your songs remotely, execute the following command:
+
+```bash
+npm run convert:remote
+```
+
+As a result, the migrator will convert all `.txt` song files from the specified source directory to `.pro` format in the
+given directory, with the following format:
+
+Under the given `GDRIVE_ROOT_FOLDER_ID` and a dynamically created directory like `/2024-04-09-17:18:05`,
+the `Aceasta mi-e dorinta sa Te-onorez.pro` will be generated and uploaded.
+Also, a `manifest.json` will be generated:
+
+```json
+{
+ "inventory": [
+ {
+ "id": "8ipLZddXG3Zy7Hbbo93Vm7",
+ "fileName": "Aceasta mi-e dorinta sa Te-onorez.txt",
+ "contentHash": "418384"
+ }
+ ],
+ "updatedOn": "2024-04-09-17:18:05"
+}
+```
+
+3. The upload will check the previous deployments (previous `manifest.json` files) and will upload only the new files.
+ If there is no previous deployment, all files will be uploaded.
+
+4. In order to sync the files with the GDrive, you can use the you can use the `sync-via-gdrive.sh` script,
+ see [this documentation](./client-sync-macos/README.md).
+
### Customization Options
You can customize the conversion process by adjusting the environment variables or by directly using
@@ -145,49 +223,52 @@ convertSongsToPP7FormatLocally({
### How It Works
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:
+the `protodump` utility for encoding and decoding presentation files. To utilize this:
```bash
git clone https://github.com/arkadiyt/protodump.git
go build -o protodump cmd/protodump/main.go
```
-### Advanced Sequencing with BES Sequence
+### FAQ
-A standout feature of the `bes-propres7-migrator` is its ability to intelligently create BES sequences in ProPresenter7,
+
+📖 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.
+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
+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
+- **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
+- **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
+- **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
+- **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.
+ 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.
+ your part.
#### Example
@@ -195,7 +276,10 @@ For a song with a specified sequence of (1,c,2,c), the migrator creates a sequen
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
+
+
+
+📖 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
@@ -204,20 +288,23 @@ 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 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.
+- **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.
+ 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.