Merge branch 'main' of https://github.com/charlesneimog/pd4web

Documentation/devs.md

@@ -1,20 +1,25 @@
-# Adding Externals (Devs)
+# Adding Externals Support (Devs)
+
+!!! warning "Content Intended for C/C++ Developers"
+    This section is intended for developers who want to interact with the `pd4web` project using JavaScript. If you are not a developer, you can skip this section.
 
 <p align="center"> Page to document the details of how you can contribute with <code>pd4web</code>. </p>
 
 ## <h2 align="center"> **pd4web**: Adding Support to Externals </h2>
 
 `pd4web` consists of a set of tools accessible via a Python module named pd4web. Internally, pd4web utilizes `EMSCRIPTEN` to compile external components into dynamic static libraries.
 
-To integrate a new library, you must create a `CMakeLists.txt`. It's highly recommended to use [pd.cmake](https://github.com/pure-data/pd.cmake) due to assumptions made (such as the TARGET name convention like earplug~ becoming earplug_tilde). After creating the `CMakeLists.txt` for the library you need, submit a pull request that modifies `Externals.yaml` within `Sources/pd4web/`. In this file, simply add a new entry similar to the provided example.
+To integrate a new library, you must create a `CMakeLists.txt`. It's highly recommended to use [pd.cmake](https://github.com/pure-data/pd.cmake) due to assumptions made (such as the TARGET name convention like `earplug~` becoming `earplug_tilde` and others). After creating the `CMakeLists.txt` for the library you need, you can submit a PR that modifies `Externals.yaml` within `Sources/pd4web/Libraries`. In this file, simply add a new entry similar to the provided example. This will make the library compatible with `pd4web`. 
+
+This is an example of how to define a library in the `Externals.yaml` file:
 
 ``` yaml
 
   - Name: cyclone # name of the pd library
     Source: GITHUB # source
     Developer: porres # in this case, Github user name
     Repository: pd-cyclone # in this case, Github Repo
-    Version: cyclone_0.7-0 # version
+    Version: cyclone_0.7-0 # version (tag name of stable commit hash)
 ```
 
 Below the complete fields for enviroment.
@@ -63,6 +68,18 @@ Below the complete fields for enviroment.
 
 ## Building the CmakeLists.txt
 
-The `CMakeLists.txt` file is the most important file for the compilation of the external. It is responsible for defining the external's name, the source files, and the dependencies. The following is an example of a `CMakeLists.txt` file for the `cyclone` library.
+The `CMakeLists.txt` file is the most important file for the compilation of the external. It defines the external's name, the source files, and the dependencies. The following is an example of a `CMakeLists.txt` file for the `earplug~` library/object.
 
 ``` cmake
+cmake_minimum_required(VERSION 3.25)
+project(earplug~)
+set(LIB_DIR "${PD4WEB_EXTERNAL_DIR}/${PROJECT_NAME}")
+
+pd_add_external(earplug~ "${LIB_DIR}/earplug.c")
+```
+
+Note that, `pd_add_external` is a function provided by the `pd.cmake` module. The first argument is the external's name, and the second argument is the source file. 
+
+The `LIB_DIR` variable is used to define the external's directory. This directory will be `${PD4WEB_EXTERNAL_DIR}` followed by the library external name defined in the `Externals.yaml` file.
+
+`PD4WEB_EXTERNAL_DIR` is a variable that points to the directory where the external's source files are located. It is defined in the `CMakeLists.txt` generated by `pd4web` (you don't need to define it).

Documentation/js/js.md

@@ -1,3 +1,6 @@
+!!! tip "Content Intended for Developers"
+    This section is intended for developers who want to interact with the `pd4web` project using JavaScript. If you are not a developer, you can skip this section.
+
 The `pd4web` project includes a WebAssembly module named `Pd4Web`. In the `index.html` file inside the `WebPatch` directory, `Pd4Web` is always loaded as follows:
 
 ``` javascript

Documentation/libraries.md

@@ -3,6 +3,12 @@ hide:
   - navigation
   - toc
 ---
+<style>
+  .md-typeset h1,
+  .md-content__button {
+    display: none;
+  }
+</style>
 
 # Supported Objects
 

Documentation/patch/Templates/score.md → Documentation/patch/Templates/1-score.md

@@ -7,8 +7,10 @@ hide:
 
 In this template you have access to a patch that receives image files (from scores) and renders it side by side with your patch. The result will be something like this:
 
+!!! tip "Click in the image to open the example in a new tab" 
+
 <p align="center">
-  <img src="../assets/score.png" width="80%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);">
+  <img src="../assets/score.png" width="80%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); cursor: pointer;" onclick="window.open('../templates/score', '_blank');">
 </p>
 
 <p align="center" markdown>
@@ -19,7 +21,7 @@ In this template you have access to a patch that receives image files (from scor
 
 ---
 
-<h3 align="center">Score Files</h3>
+## <h2 align="center">What should your patch include?</h2>
 
 
 You make your patch and the score file can be set using the object `[s pd4web-score]`. I recomend to use svg files, but you can use any image file (.png, .jpeg). 
@@ -30,7 +32,7 @@ You make your patch and the score file can be set using the object `[s pd4web-sc
 
 ---
 
-<h3 align="center">Add infos in the website</h3>
+## <h3 align="center">Extra options</h3>
 
 
 After compile the patch, you will see that, inside the folder `WebPatch`, will have a file called `bula.md`. Inside this file, you can write some description about your piece. The file uses markdown to render, you can check the complet syntax in https://www.markdownguide.org/basic-syntax/. Below the example of main command:

Documentation/patch/Templates/hands.md → Documentation/patch/Templates/2-hands.md

@@ -13,14 +13,14 @@ The result will be something like this:
 ---
 
 <p align="center">
-  <img src="../assets/ml5.png" width="50%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);">
+  <img src="../assets/ml5.png" width="50%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); cursor: pointer;" onclick="window.open('../templates/ml5', '_blank');">
 </p>
 
 <p align="center" markdown>
     :octicons-download-16: [Download Patch example](../patches/template-2.pd)
 </p>
 
-<h2 align="center">How must be your patch</h2>
+## <h2 align="center">What should your patch include?</h2>
 
 You patch must have some receivers using the `L-` and `R-` preffixes to receive the data from the hands followed by the number of the position you want, following the image below:
 
@@ -38,13 +38,10 @@ For example, to receive the data from where is the `INDEX_FINGER_TIP` for the `L
 
 From these receivers, you will get two numbers, `x` and `y`, inside a list. These numbers represent the position of your hand relative to your real-time video.
 
-- The `x` value indicates the vertical position: 
-  - Close to `0` means your hand is near the top of the image.
-  - Close to `1` means your hand is near the bottom of the image.
-
-- The `y` value indicates the horizontal position:
-  - Close to `0` means your hand is near the left side of the image.
-  - Close to `1` means your hand is near the right side of the image. 
+<div class="grid cards" markdown>
+  - __X Position__: `0` is the top and `1` is the bottom.
+  - __Y Position__: `0` is the left and `1` is the right.
+</div>
 
 In summary, `[x, y]` defines the hand's position within a coordinate system where `(0,0)` is the top-left corner and `(1,1)` is the bottom-right corner of the image.
 

Documentation/patch/Templates/choir.md → Documentation/patch/Templates/3-choir.md

@@ -13,25 +13,25 @@ The result will be something like this:
 ---
 
 <p align="center">
-  <img src="../assets/choir.jpeg" width="35%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);">
+  <img src="../assets/choir.jpeg" width="35%" style="border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); cursor: pointer;" onclick="window.open('https://charlesneimog.github.io/Pandemonio/', '_blank');">
 </p>
 
 <p align="center" markdown>
     :octicons-download-16: [Download Patch example](../patches/template-3.pd)
 </p>
 
-<h2 align="center">How must be your patch</h2>
+## <h2 align="center">What should your patch include?</h2>
 
-In your patch, you have these options to set using **senders**:
+In your patch, you have these options to set using **senders**, for example, `[s composer`], `[s title]`, `[s duration-bar]`, `[s piece-duration-bar]`, `[s poem-phrase]` and `[s pitch-syl]`:
 
 - `composer`: The composer name;
 - `title`: Title of the piece;
-- `duration-bar`: A number between 0 and 100 for the bar line.
-- `piece-duration-bar`: A number between 0 and 100 for the bar line.
+- `duration-bar`: A number between 0 and 100 for the bar line (control the bar above the score);
+- `piece-duration-bar`: A number between 0 and 100 for the bar line (control the bar below the phrase);
 - `poem-phrase`: The complete phrase of the poem (or anything else), for example `minha frase`.
 - `pitch-syl`: A list with the pitchname and the syllable, for example `C4 fra`.
 
-In your patch, you have these options to set using **receivers**:
+In your patch, you have these options to set using **receivers**, for example, `[r naipe]`:
 
 - `naipe`. Receive the naipe choosen by the singer, 1 for Baixo, 2 for Tenor, 3 for Contralto and 4 for Soprano.
 

Documentation/patch/Templates/4-p5js.md

@@ -0,0 +1,23 @@
+---
+hide:
+ - toc
+---
+
+# <h1 align="center">Template <code>4</code>: p5js and pd4web</h1>
+
+!!! tip "Template designed for those who know how to program"
+    Learn how to program, I really recommend watch the [Coding Train](https://www.youtube.com/user/shiffman) channel. It is a great channel to learn how to program in a fun way. 
+
+This template is for the combination of `p5js` and `pd4web`. It is a simple template that uses the `p5js` library to create a canvas and pd4web to create a patch that can be used to control the canvas (or vice-versa).
+
+<p align="center">
+  <img src="../assets/p5js.png" width="80%" style="cursor: pointer; border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);" onclick="window.open('./../templates/p5js', '_blank');" >
+</p>
+
+<p align="center" markdown>
+    :octicons-download-16: [Download Patch Template](../patches/template-4.zip)
+</p>
+
+There is no much to say about this template, it just use a personalized `index.html` and `sketch.js`, where you can code you `p5js` code. 
+
+Just download and have fun. If you have any question, please, let me know. If you have some questions about `p5js` or `pd4web` you can ask me too. I will be glad to help you.

Documentation/patch/Templates/5-tutorial.md

@@ -0,0 +1,28 @@
+---
+hide:
+ - toc
+---
+
+# <h1 align="center">Template <code>5</code>: Tutorial Patches</h1>
+
+Patch side by side with some text to explain the patch. The result will be something like this:
+
+<p align="center">
+    <img src="../assets/tutorial.png" width="80%" style="cursor: pointer; border-radius: 10px; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);" onclick="window.open('./../templates/tutorial', '_blank');">
+</p>
+
+To make the description again we use a markdown file. The markdown is called `tutorial.md` and is located in the `WebPatch` folder. The content of the file should be edited after compilation of the patch.
+
+As in the previous template, inside `tutorial.md` you can write some description about the patch. The file uses markdown to render, you can check the complet syntax in https://www.markdownguide.org/basic-syntax/. Below the example of main command:
+
+``` md
+# Title 1
+## Title 2
+### Title 3
+
+**bold text**
+*italic text**
+
+* this one item
+* this is another item
+```

Documentation/patch/Templates/index.md

@@ -4,13 +4,19 @@ Website templates are predefined websites that can be used to expand what you ca
 
 --- 
 <div class="grid cards" markdown>
--   :musical_score: [__`1` - Patch + Score__](score.md)
--   :hand_splayed_tone3: [__`2` - Hand detection (AI)__](hands.md)
+-   :musical_score: [__`1` - Patch + Score__](1-score.md)
+-   :hand_splayed_tone3: [__`2` - Hand detection (AI)__](2-hands.md)
 </div>
 
 --- 
 <div class="grid cards" markdown>
--   :material-church: [__`3` - Choir__](choir.md)
--   :simple-p5dotjs: [__`4` - pd4web + p5js__](p5js.md)
+-   :material-church: [__`3` - Choir__](3-choir.md)
+-   :simple-p5dotjs: [__`4` - pd4web + p5js__](4-p5js.md)
 
 </div>
+
+--- 
+<div class="grid cards" markdown>
+-   :octicons-book-16: [__`5` - Tutorial patches__](5-tutorial.md)
+-   :octicons-book-16: [__`5` - Tutorial patches__](5-tutorial.md)
+</div>

Documentation/patch/Templates/templates/ml5/index.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Pd4Web</title>
+    <meta charset="UTF-8" />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.11.1/p5.min.js"></script>
+    <script src="https://unpkg.com/ml5@1/dist/ml5.js"></script>
+    <script src="./pd4web.threads.js"></script>
+    <script src="./pd4web.js"></script>
+    <script src="./sketch.js"></script>
+    <style>
+      canvas {
+        border-radius: 30px;
+      }
+    </style>
+  </head>
+  <body>
+    <span class="pd4web-sound-switch" id="Pd4WebAudioSwitch"></span>
+    <div id="Pd4WebPatchDiv"class="Pd4WebPatchDiv">
+      <svg id="Pd4WebCanvas"></svg>
+    </div>
+    <hr>
+    <p id="message" style="text-align: center; font-size: 20px">
+      Click on the page to request access to the camera and microphone.
+    </p>
+    <div style="display: flex; justify-content: center; border-radius: 30px">
+      <div id="p5js" style="border-radius: 30px"></div>
+    </div>
+
+
+    <script>
+      // ╭─────────────────────────────────────╮
+      // │        Gui Bottoms Interface        │
+      // ╰─────────────────────────────────────╯
+      var Pd4Web = null;
+
+      // add window click event to start video
+      document.addEventListener("click", async () => {
+        navigator.mediaDevices.getUserMedia({
+          video: true,
+          audio: true
+        });
+        if (Pd4Web) {
+          return;
+        }
+        Pd4WebModule().then((Pd4WebModulePromise) => {
+          Pd4Web = new Pd4WebModulePromise.Pd4Web();
+          const message = document.getElementById("message");
+          if (message) {
+            message.style.display = "none";
+          }
+        });
+        // remove event listener
+        document.removeEventListener("click", () => {});
+      });
+
+      document
+        .getElementById("Pd4WebAudioSwitch")
+        .addEventListener("click", async () => {
+          startVideo();
+          Pd4Web.init();
+          console.log("Pd4Web", Pd4Web);
+        });
+    </script>
+  </body>
+</html>

Documentation/patch/Templates/templates/ml5/index.pd

@@ -0,0 +1,60 @@
+#N canvas 121 80 1282 686 10;
+#X obj 3 3 tgl 45 0 s-tgl1 r-tgl1 empty 0 -8 0 10 #fcfcfc #000000 #000000 0 1;
+#X obj 153 2 tgl 45 0 s-tgl2 r-tgl2 empty 0 -8 0 10 #fcfcfc #000000 #000000 0 1;
+#X obj 153 90 tgl 45 0 s-tgl4 r-tgl4 empty 0 -8 0 10 #fcfcfc #000000 #000000 0 1;
+#X obj 3 90 tgl 45 0 s-tgl3 r-tgl3 empty 0 -8 0 10 #fcfcfc #000000 #000000 0 1;
+#X obj 208 4 r R-8;
+#N canvas 266 303 622 364 tgl2 0;
+#X obj 2 33 unpack f f;
+#X obj 2 74 change;
+#X obj 2 119 s r-tgl2;
+#X obj 2 53 expr if ($f1 > 0.9 && $f2 < 0.2 \, 1 \, 0);
+#X obj 2 4 inlet;
+#X connect 0 0 3 0;
+#X connect 0 1 3 1;
+#X connect 1 0 2 0;
+#X connect 3 0 1 0;
+#X connect 4 0 0 0;
+#X restore 257 94 pd tgl2;
+#N canvas 266 303 622 364 tgl1 0;
+#X obj 2 4 inlet;
+#X obj 1 25 unpack f f;
+#X obj 1 45 expr if ($f1 < 0.2 && $f2 < 0.2 \, 1 \, 0);
+#X obj 1 111 s r-tgl1;
+#X obj 1 66 change;
+#X connect 0 0 1 0;
+#X connect 1 0 2 0;
+#X connect 1 1 2 1;
+#X connect 2 0 4 0;
+#X connect 4 0 3 0;
+#X restore 209 94 pd tgl1;
+#N canvas 266 303 622 364 tgl3 0;
+#X obj 2 33 unpack f f;
+#X obj 2 74 change;
+#X obj 2 4 inlet;
+#X obj 2 53 expr if ($f1 < 0.2 && $f2 > 0.8 \, 1 \, 0);
+#X obj 2 119 s r-tgl3;
+#X connect 0 0 3 0;
+#X connect 0 1 3 1;
+#X connect 1 0 4 0;
+#X connect 2 0 0 0;
+#X connect 3 0 1 0;
+#X restore 306 94 pd tgl3;
+#N canvas 266 303 622 364 tgl4 0;
+#X obj 2 33 unpack f f;
+#X obj 2 74 change;
+#X obj 2 4 inlet;
+#X obj 2 53 expr if ($f1 > 0.8 && $f2 > 0.8 \, 1 \, 0);
+#X obj 2 119 s r-tgl4;
+#X connect 0 0 3 0;
+#X connect 0 1 3 1;
+#X connect 1 0 4 0;
+#X connect 2 0 0 0;
+#X connect 3 0 1 0;
+#X restore 355 94 pd tgl4;
+#X text 38 57 Use your right hand!;
+#X connect 4 0 5 0;
+#X connect 4 0 6 0;
+#X connect 4 0 7 0;
+#X connect 4 0 8 0;
+#X coords 0 -1 1 1 200 140 1 0 0;