From d243db4113ac8c3b3242ebc16da230f255c315c4 Mon Sep 17 00:00:00 2001 From: Ioan Lucut Date: Tue, 9 Apr 2024 21:08:27 +0300 Subject: [PATCH] Update documentation --- README.md | 159 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 123 insertions(+), 36 deletions(-) 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.