Docs: Add reference and tutorial for Shake processor

assets/scores/reference/processes/ShakeExample.score

@@ -0,0 +1 @@
+{"Document":{"ObjectName":"Scenario::ScenarioDocumentModel","id":1,"BaseScenario":{"ObjectName":"Scenario::BaseScenario","id":0,"Constraint":{"ObjectName":"Scenario::IntervalModel","id":0,"Metadata":{"ScriptingName":"ShakeExample","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[{"uuid":"9906e563-ddeb-4ecd-908c-952baee2a0a5","ObjectName":"SignalDisplay","id":2,"Metadata":{"ScriptingName":"Signal display","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Duration":10584000000,"Height":300.0,"StartOffset":0,"LoopDuration":10584000000,"Pos":[-298.67999999999995,-92.918],"Size":[582.0,314.0],"Loops":true,"Inlets":[{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":0,"Hidden":true,"Custom":"in","Exposed":"in","Value":{},"Init":{},"Domain":{}}],"Outlets":[{"uuid":"3620ea94-5991-41cf-89b3-11f842cc39d0","ObjectName":"Outlet","id":0,"Hidden":true,"Custom":"out","Exposed":"out","Value":{"Tuple":[{"Float":0.9585777521133423},{"Float":19.91214942932129}]},"Domain":{}}]},{"uuid":"de035912-5b03-49a8-bc4d-b2cba68e21d9","ObjectName":"Scenario","id":1,"Metadata":{"ScriptingName":"Scenario.1","Comment":"","Color":"Transparent1","Label":"","Touched":false},"Duration":10584000000,"Height":1500.0,"StartOffset":0,"LoopDuration":10584000000,"Pos":[-341.0,-459.0],"Size":[722.0,325.0],"Loops":false,"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"In","Exposed":"in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Out","Exposed":"out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"StartTimeNodeId":0,"StartEventId":0,"StartStateId":0,"Exclusive":false,"TimeNodes":[{"ObjectName":"Scenario::TimeSyncModel","id":0,"Metadata":{"ScriptingName":"Sync.start","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":0,"Events":[0],"MusicalSync":-1.0,"AutoTrigger":false,"Start":true,"Active":false,"Expression":" { true == false } "},{"ObjectName":"Scenario::TimeSyncModel","id":1,"Metadata":{"ScriptingName":"Sync.laue34","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":674044946,"Events":[1],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":false,"Expression":" { true == false } "},{"ObjectName":"Scenario::TimeSyncModel","id":2,"Metadata":{"ScriptingName":"Sync.axis84","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":10134166830,"Events":[2],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":false,"Expression":" { true == false } "}],"Events":[{"ObjectName":"Scenario::EventModel","id":0,"Metadata":{"ScriptingName":"Event.start","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":0,"States":[0],"Condition":"","Date":0,"Offset":0},{"ObjectName":"Scenario::EventModel","id":1,"Metadata":{"ScriptingName":"Event.lilt94","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":1,"States":[1],"Condition":"","Date":674044946,"Offset":0},{"ObjectName":"Scenario::EventModel","id":2,"Metadata":{"ScriptingName":"Event.omen13","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":2,"States":[2],"Condition":"","Date":10134166830,"Offset":0}],"States":[{"ObjectName":"Scenario::StateModel","id":0,"Metadata":{"ScriptingName":"State.start","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":0,"PreviousConstraint":null,"NextConstraint":1,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},{"ObjectName":"Scenario::StateModel","id":1,"Metadata":{"ScriptingName":"State.zeta20","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":1,"PreviousConstraint":1,"NextConstraint":2,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},{"ObjectName":"Scenario::StateModel","id":2,"Metadata":{"ScriptingName":"State.glut10","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":2,"PreviousConstraint":2,"NextConstraint":null,"HeightPercentage":0.05466666666666667,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]}],"Constraints":[{"ObjectName":"Scenario::IntervalModel","id":1,"Metadata":{"ScriptingName":"Interval.slab30","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[],"SmallViewRack":[],"FullViewRack":[],"DefaultDuration":674044946,"MinDuration":674044946,"MaxDuration":674044946,"GuiDuration":741449440,"Speed":1.0,"Rigidity":true,"MinNull":false,"MaxInf":false,"Signatures":[],"StartState":0,"EndState":1,"StartDate":0,"HeightPercentage":0.05466666666666667,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":-1.0,"Center":0,"ViewMode":0,"SmallViewShown":false,"HasSignature":false},{"ObjectName":"Scenario::IntervalModel","id":2,"Metadata":{"ScriptingName":"Shake","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Inlet":{"uuid":"a1574bb0-cbd4-4c7d-9417-0c25cfd1187b","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Audio in","Exposed":"audio in"},"Outlet":{"uuid":"a1d97535-18ac-444a-8417-0cbc1692d897","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Audio out","Exposed":"audio out","GainInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10000,"Hidden":false,"Custom":"Gain","Exposed":"gain","Value":{},"Init":{},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},"PanInlet":{"uuid":"9a13fb32-269a-47bf-99a9-930188c1f19c","ObjectName":"Inlet","id":10001,"Hidden":false,"Custom":"Pan","Exposed":"pan","Value":{},"Init":{},"Domain":{}},"Gain":1.0,"Pan":[1.0,1.0],"Propagate":true},"Processes":[{"uuid":"ecb5dc46-164c-46a0-a01e-90e3c3bd7527","ObjectName":"puara_shake","id":1,"Metadata":{"ScriptingName":"Shake","Comment":"","Color":"Transparent1","Label":"","Touched":true},"Duration":9460121884,"Height":300.0,"StartOffset":0,"LoopDuration":7056000000,"Pos":[82.0,-3.0],"Size":[75.0,22.0],"Loops":false,"Inlets":[{"uuid":"769dd38a-bfb3-4dc6-b52a-b6abb7afe2a3","ObjectName":"Inlet","id":0,"Hidden":false,"Custom":"Acceleration","Exposed":"acceleration","Address":"OSC:/accelerometer"},{"uuid":"edb5dc46-164c-46a0-a11e-90e3c3bd7527","ObjectName":"Inlet","id":1,"Hidden":true,"Custom":"Integrator Frequency (Hz)","Exposed":"integrator frequency (hz)","Value":{"Float":10.0},"Init":{"Float":10.0},"Domain":{"Float":{"Min":0.0,"Max":200.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":2,"Hidden":true,"Custom":"Fast Leak","Exposed":"fast leak","Value":{"Float":0.6000000238418579},"Init":{"Float":0.6000000238418579},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":3,"Hidden":true,"Custom":"Slow Leak","Exposed":"slow leak","Value":{"Float":0.30000001192092896},"Init":{"Float":0.30000001192092896},"Domain":{"Float":{"Min":0.0,"Max":1.0}}},{"uuid":"82427d27-084a-4ab6-9c4e-db83929a1200","ObjectName":"Inlet","id":4,"Hidden":true,"Custom":"Activation Threshold","Exposed":"activation threshold","Value":{"Float":0.10000000149011612},"Init":{"Float":0.10000000149011612},"Domain":{"Float":{"Min":0.0,"Max":1.0}}}],"Outlets":[{"uuid":"cff96158-cc72-46d7-99dc-b6038171375b","ObjectName":"Outlet","id":0,"Hidden":false,"Custom":"Output","Exposed":"output"}]}],"SmallViewRack":[{"Processes":[1],"Process":null,"Height":245.0,"Nodal":true}],"FullViewRack":[{"Process":0,"Nodal":true}],"DefaultDuration":9460121884,"MinDuration":9460121884,"MaxDuration":9460121884,"GuiDuration":9535372853,"Speed":1.0,"Rigidity":true,"MinNull":false,"MaxInf":false,"Signatures":[],"StartState":1,"EndState":2,"StartDate":674044946,"HeightPercentage":0.05466666666666667,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":-1.0,"Center":0,"ViewMode":0,"SmallViewShown":true,"HasSignature":false}],"Comments":[]}],"SmallViewRack":[{"Processes":[2],"Process":2,"Height":200.0,"Nodal":false}],"FullViewRack":[{"Process":1,"Nodal":false},{"Process":2,"Nodal":false}],"DefaultDuration":10584000000,"MinDuration":10584000000,"MaxDuration":11113200000,"GuiDuration":11642400000,"Speed":1.0,"Rigidity":false,"MinNull":false,"MaxInf":true,"Signatures":[[0,[4,4]]],"StartState":0,"EndState":1,"StartDate":0,"HeightPercentage":0.0,"NodalSlotHeight":100.0,"QuantizationRate":-1.0,"Zoom":15120000.0,"Center":0,"ViewMode":1,"SmallViewShown":true,"HasSignature":true},"StartTimeNode":{"ObjectName":"Scenario::TimeSyncModel","id":0,"Metadata":{"ScriptingName":"Sync.start","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":0,"Events":[0],"MusicalSync":-1.0,"AutoTrigger":false,"Start":true,"Active":false,"Expression":" { true == false } "},"EndTimeNode":{"ObjectName":"Scenario::TimeSyncModel","id":1,"Metadata":{"ScriptingName":"Sync.end","Comment":"","Color":"Gray","Label":"","Touched":true},"Date":10584000000,"Events":[1],"MusicalSync":-1.0,"AutoTrigger":false,"Start":false,"Active":true,"Expression":" { true == false } "},"StartEvent":{"ObjectName":"Scenario::EventModel","id":0,"Metadata":{"ScriptingName":"Event.start","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":0,"States":[0],"Condition":"","Date":0,"Offset":0},"EndEvent":{"ObjectName":"Scenario::EventModel","id":1,"Metadata":{"ScriptingName":"Event.end","Comment":"","Color":"Emphasis4","Label":"","Touched":true},"TimeNode":1,"States":[1],"Condition":"","Date":10584000000,"Offset":0},"StartState":{"ObjectName":"Scenario::StateModel","id":0,"Metadata":{"ScriptingName":"State.start","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":0,"PreviousConstraint":null,"NextConstraint":0,"HeightPercentage":0.0,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]},"EndState":{"ObjectName":"Scenario::StateModel","id":1,"Metadata":{"ScriptingName":"State.end","Comment":"","Color":"Base1","Label":"","Touched":true},"Event":1,"PreviousConstraint":0,"NextConstraint":null,"HeightPercentage":0.0,"Messages":{"Name":"","Accessors":[],"Unit":"none","Previous":[],"Following":[],"User":null,"Priorities":[1,2,0]},"Controls":[],"StateProcesses":[]}},"Speed":1.0,"Cables":[{"ObjectName":"Process::Cable","id":1,"Type":0,"Source":[{"ObjectName":"Scenario::ScenarioDocumentModel","ObjectId":1},{"ObjectName":"Scenario::BaseScenario","ObjectId":0},{"ObjectName":"Scenario::IntervalModel","ObjectId":0},{"ObjectName":"Scenario","ObjectId":1},{"ObjectName":"Scenario::IntervalModel","ObjectId":2},{"ObjectName":"puara_shake","ObjectId":1},{"ObjectName":"Outlet","ObjectId":0}],"Sink":[{"ObjectName":"Scenario::ScenarioDocumentModel","ObjectId":1},{"ObjectName":"Scenario::BaseScenario","ObjectId":0},{"ObjectName":"Scenario::IntervalModel","ObjectId":0},{"ObjectName":"SignalDisplay","ObjectId":2},{"ObjectName":"Inlet","ObjectId":0}]}],"BusIntervals":[]},"Plugins":[{"uuid":"1f923578-08c3-49be-9ba9-69c144ee2e32","Refresh":false,"Reconnect":false,"MidiRatio":1.0},{"uuid":"6e610e1f-9de2-4c36-90dd-0ef570002a21","RootNode":{},"Children":[{"Device":{"Name":"OSC","Protocol":"9a42de4b-f6eb-4bca-9564-01b975f601b9","Config":{"Mode":1,"Version":0,"Framing":1,"Bundle":0,"Transport":{"UDP":{"Local":{"Bind":"0.0.0.0","Port":9997},"Remote":{"Host":"127.0.0.1","Port":9996,"Broadcast":false}}}}},"Children":[{"Address":{"ioType":"<->","ClipMode":"Free","RepetitionFilter":false,"Value":{"Vec3f":[-0.004788403399288654,0.2777273952960968,9.418789863586426]},"Domain":{},"Name":"accelerometer"}}]}]}],"Version":4,"Commit":"e7fcc31bb79d240c34f9a9d7bf1bc1a88a3eed89","Tag":"3.5.2"}

docs/common-practices/tutorial-shake-gestures.md

@@ -0,0 +1,51 @@
+---
+layout: default
+title: 'Detecting Shake Gestures'
+parent: Common practices
+nav_order: 28
+---
+
+# Detecting Shake Gestures
+
+The Puara **Shake** processor is designed to detect energetic shaking motions from a device. Unlike the `Roll` or `Tilt` processors, it only requires accelerometer data, making it a simple yet powerful tool for gestural interaction.
+
+This tutorial will show you how to set up the `Shake` processor using a smartphone as a sensor and how to tune its parameters to customize the gesture detection.
+
+### Part 1: Setting Up the Live Sensor Data
+
+We'll use a smartphone app to stream accelerometer data from a phone. This tutorial uses **[Sensors2OSC](https://sensors2.org) (Android)**, but the setup is similar for iPhone apps like **[GyroOSC](https://www.bitshapesoftware.com/instruments/gyrosc/)**.
+
+1.  **Configure the App:** In the Sensors2OSC settings, set the **Host** to your computer's IP address and the **Port** to `9997`.
+    <img src="/assets/images/reference/processes/puara/sensors-to-osc-settings.jpeg" alt="Sensors2OSC Settings" width="40%">
+
+2.  **Enable the Accelerometer:** On the app's main screen, you only need to enable the **Accelerometer**. Then, enable the main **Send data** toggle at the top.
+    <img src="/assets/images/reference/processes/puara/sensors-to-osc-main.jpeg" alt="Sensors Enabled" width="40%">
+
+3.  **Set up OSC in score:** In the Device Explorer, add a new OSC device and set its **`score listening port`** to `9997`.
+
+4.  **Learn the OSC Address:** Right-click the new OSC device and select `Learn`. Shake your phone until you see the `/accelerometer` address appear, then click OK.
+    <img src="/assets/images/reference/processes/puara/score-to-osc-learn-accelerometer.png" alt="OSC Learning Accelerometer" width="50%">
+    *(Note: You can reuse the general learning image, but this one is more specific to the task)*
+
+### Part 2: Building the Shake Gesture Patch
+
+With the sensor data streaming, we can build our scenario.
+
+1.  **Add Processes:** From the Process Library, add a `Gestures/Shake` processor and a `Monitoring/Signal display`.
+
+2.  **Connect the Input:** Drag the `/accelerometer` address from the Device Explorer directly onto the `Acceleration` input of the Shake processor.
+
+3.  **Visualize the Output:** Connect the `Output` of the Shake processor to the `Signal display`.
+
+4.  **Run and Test!** Run the scenario. Shake your phone and watch the signal display. You'll see the output value rise and fall with your motion.
+
+<img src="/assets/images/reference/processes/puara/shake-processor-example.png" alt="Shake Processor Example" width="100%">
+
+### Part 3: Tuning the Response
+
+The power of the Shake processor lies in its parameters. Try adjusting them while the scenario is running:
+*   **Activation Threshold:** Increase this to make the detector less sensitive, requiring a more vigorous shake to trigger a response.
+*   **Fast Leak:** Lower this value to make the output rise much more sharply when you shake the device.
+*   **Slow Leak:** Lower this value to make the output drop to zero almost instantly when you stop shaking. Increase it to make the value fade out more slowly.
+
+You can download a complete example score here: [/assets/scores/reference/processes/ShakeExample.score](/assets/scores/reference/processes/ShakeExample.score)