Update documentation

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,57 +223,63 @@ 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,
+<details>
+<summary>📖 Advanced Sequencing with BES Sequence.</summary>
+
+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
 
 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
+</details>
+
+<details>
+<summary>📖 Initial Setup Slide with Macro Reference</summary>
 
 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.
+
+</details>
 
 <details>
 <summary>📖 How to regenerate the `.proto` files when a new version of `ProPresenter7` arrives.</summary>