Skip to content

Commit ad2ee29

Browse files
pandrrpandrr
committed
starting cables
2 parents 95feaba + f90ee1b commit ad2ee29

File tree

22 files changed

+316
-56
lines changed

22 files changed

+316
-56
lines changed

‎md/4_export_embed/dev_embed/export_standalone/export_standalone.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# Export for Cables Standalone Version
1+
# Export full Patch
22

3-
Select the "Standalone" option in the export dialog on [dev.cables.gl](https://dev.cables.gl). Download the latest version of ["cables standalone"](https://dev.cables.gl/downloads).
3+
Select the "Patch" option in the export dialog on [dev.cables.gl](https://dev.cables.gl). This export will contain
4+
all the assets, any custom ops of the patch (patch, team, subpatch) and can be run in cables standalone.
45

5-
Install and/or open the standalone version, select "Open Patch" from the menu or the welcome screen, select
6-
the `.json` file you just downloaded. Start patching!
6+
## Run in cables standalone
77

8-
Be aware, that there is currently no way to re-import patches that you worked on in "cables standalone"
9-
to cables.gl. This will be in one of the next releases!
8+
Download the latest version of ["cables standalone"](https://dev.cables.gl/downloads).
109

11-
Have a look at [our roadmap](https://github.com/cables-gl/cables_electron/milestones?direction=desc&sort=due_date&state=open) for future versions and [report bugs](https://github.com/cables-gl/cables_electron/issues) or submit [feature requests](https://github.com/cables-gl/cables_electron/issues). Any feedback is greatly appreciated!
10+
Install and/or open the standalone version, select "Open Patch" from the menu or the welcome screen, select
11+
the `.cables` file you just downloaded. Start patching!

‎md/6_1_developing_cables/5_standalone_as_devenv/standalone_as_devenv.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Using standalone to develop cables
2+
3+
## Set Up
4+
5+
* the preferred way of developing cables locally is using the `cables_dev` repository: https://github.com/cables-gl/cables_dev
6+
* that repo contains scripts that will set up everything for you to get started
7+
* Read up about setting up everything for you to start contributing to cables in the section on how to ["Set up local environment"](../1_setup_dev_env/setup_dev_env)
8+
of the official cables documentation.
9+
10+
<a id="dev"></a>
11+
## Build / Dev
12+
13+
Once the above steps are done, continue below, deciding beforehand if you want to improve your local version of cables standalone,
14+
develop on cables core or editor, or would like to build and package a finished executable.
15+
16+
### Local Build
17+
18+
- set up your local environment (see above)
19+
- change to `cables_electron` directory (`cd cables_electron`)
20+
- run `npm install --no-save`
21+
- run `npm run build` to build the standalone version
22+
- run `npm run start` to start the standalone from the checked out sources
23+
24+
### Local Development
25+
26+
- set up your local environment (see above)
27+
- change to `cables_electron` directory (`cd cables_electron`)
28+
- run `npm install --no-save`
29+
- run `npm run build`
30+
- use `npm run start` to start the app
31+
- this will start watchers for changes in client-side javascript dirs (e.g. `src_client` and `../shared/client/`
32+
- when making changes to files in these directories, a reload of the electron app is enough to see the changes (Cmd/Ctrl+R)
33+
- if you want to develop on ops and/or the ui, change to cables_dev (`cd ..`) and run `npm run watch:standalone`
34+
- this will create watchers on files in `cables` and `cables_ui` that trigger a rebuild on change
35+
- when making changes to files in these directories, a reload of the electron app is enough to see the changes (Cmd/Ctrl+R)
36+
37+
### Building an executable
38+
39+
- take the steps that are described in "Local Build" above
40+
- use `npm run pack` or `npm run dist` (will try to sign the exe) - add `:mac`, `:win`, `:linux` to only build one architecture
41+
- find the executable in `dist/`

‎md/6_1_developing_cables/developing_cables.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Developing Cables
22

3-
setup your local enviroment to contribute to cables-development
3+
setup your local environment to contribute to cables-development
44

55
__TOC__

‎md/6_2_standalone/0_general/general.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# General
2+
3+
## What is Cables Standalone?
4+
5+
Cables [Standalone](https://cables.gl/standalone) is an electron build of the [cables editor](https://github.com/cables-gl/cables_ui), , [cables core](https://github.com/cables-gl/cables) and all the [Ops](https://cables.gl/ops) that make up cables.gl.
6+
7+
Some use-cases for the standalone version are:
8+
9+
- Use it to work on [exported patches](../../4_export_embed/dev_embed/export_standalone/export_standalone) while offline.
10+
- Use it to run installations or vj-sets without access to [cables.gl](https://cables.gl).
11+
- Keep your assets in local files, no need to upload to a web server...ensuring privacy.
12+
- Make use of native features using npm packages and not being bound by browser-sandboxing.
13+
- Develop your own Ops using your editor of choice.
14+
- Contribute to cables-development using the standalone as your [development environment](../../6_1_developing_cables/developing_cables).
15+
- Keep a certain version of cables next to [your project](../../4_export_embed/dev_embed/export_standalone/export_standalone) for backup purposes.
16+
17+
While the standalone facilitates for offline use and local development of patches, it's still possible to [import](https://dev.cables.gl/mydata#import) your
18+
work "back" to cables.gl and share it with the community, gather likes and comments and help others to learn via your work.

‎md/6_2_standalone/1_coding_ops/coding_ops.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Coding Ops
2+
3+
Cables standalone comes with [all the ops](https://cables.gl/ops) on cables.gl, all the [extensions](https://cables.gl/ops/Ops.Extension) and a few [special ops](https://cables.gl/ops/Ops.Extension.Standalone)
4+
that only work when using the standalone version.
5+
6+
You can use cables standalone to [code your own ops](../../5_writing_ops/coding_ops). A few concepts are slightly different
7+
from how things work in the browser and on the web. Here is what's different:
8+
9+
## Op directories
10+
11+
One big difference to how things work on [cables.gl](https://cables.gl) is, that you can have ops from different sources
12+
on your hard disk. You can individually pick different directories, collections of ops and their code per project and
13+
cables will then load the relevant ops for your.
14+
15+
![op dir](img/nav.png)
16+
17+
All the ops in the directories are sorted into a hierarchy, should they have the same name, the "topmost" one wins.
18+
This way you can easily override (for example) core-ops with your own implementation, swap out collections of ops
19+
with the ones from your colleagues or try out new operators real quick.
20+
21+
You can re-order the hierarchy in the "Manage Op Directories"-tab:
22+
23+
![manage_dirs](img/manage_dirs.png)
24+
25+
## Using an external editor
26+
27+
Every op that you use in a standalone project registers a listener in the file system to listen for changes. If you open
28+
the op's JavaScript file in any external editor you can edit the code and see the changes reflect immediately. To get
29+
to the op's directory quickly, click on the folder-icon in the "Manage Op"-tab.
30+
31+
![op dir](img/op_dir.png)
32+

‎md/6_2_standalone/1_coding_ops/img/manage_dirs.png

37.3 KB
Loading

‎md/6_2_standalone/1_coding_ops/img/nav.png

12 KB
Loading

‎md/6_2_standalone/1_coding_ops/img/op_dir.png

25.7 KB
Loading

‎md/6_2_standalone/2_sharing_ops/img/add_npm.png

19.5 KB
Loading

‎md/6_2_standalone/2_sharing_ops/img/corelib.png

21.6 KB
Loading

‎md/6_2_standalone/2_sharing_ops/sharing_ops.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Sharing ops
2+
3+
The simplest way of sharing ops is to just share the op directory with people. Package things into subdirectories
4+
that have the op-name, make sure it has a reasonably unique name, delete the [node_modules](../3_using_npm/using_npm)-folder
5+
if needed and publish the directory however you want. Other people can then download the directory and add it to their projects
6+
as shown above.
7+
8+
### Op packages
9+
10+
If you want to share a set of Ops with other people on the internet, you can create an op-package. This package
11+
adheres to the `package.json` standard that npm uses and can be installed via `npm install`.
12+
13+
Make sure your `package.json` lists all the needed files in the `files` section and your way of distributing these
14+
ops is compatible with [npm install](https://docs.npmjs.com/cli/v10/commands/npm-install#description).
15+
16+
A simple example:
17+
```json
18+
{
19+
"name": "Ops.Extension.Standalone.Net.Osc",
20+
"version": "0.0.1",
21+
"files": [
22+
"Ops.Extension.Standalone.Net.Osc.json",
23+
"Ops.Extension.Standalone.Net.Osc.js",
24+
"Ops.Extension.Standalone.Net.Osc.md"
25+
]
26+
}
27+
```

‎md/6_2_standalone/3_using_npm/img/add_npm.png

19.5 KB
Loading

‎md/6_2_standalone/3_using_npm/img/corelib.png

21.6 KB
Loading

‎md/6_2_standalone/3_using_npm/using_npm.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Using NPM
2+
3+
## What is NPM?
4+
5+
NPM stands for the [node package manager](https://www.npmjs.com/) and is a widely used tool to manage dependencies
6+
of applications developed in JavaScript. It also features access to a vast collection of libraries written in
7+
JavaScript that can (potentially) be used in cables standalone.
8+
9+
## Why NPM?
10+
11+
Cables standalone in not being bound to the browser-sandbox anymore and has more direct access to features of
12+
the underlying operating system. This makes it possible to you a lot of the packages on [npmjs.com](https://www.npmjs.com/)
13+
in ops. Features like access to the [file system](https://cables.gl/ops/Ops.Extension.Standalone.Files), [network interfaces](https://cables.gl/ops/Ops.Extension.Standalone.Net), or [native binaries](https://cables.gl/op/Ops.Extension.Standalone.Ffmpeg) opens up a
14+
whole new set of possibilities to work with cables.
15+
16+
## How do I add a library to my Op?
17+
18+
Once you created or cloned your own Op, you can use any npm package by adding it on the "Manage Op"-Tab. Enter its
19+
name as it appears on npmjs.org. So e.g. `npm install osc-js` becomes `osc-js`, if you want to add a fixed version to your
20+
package add it to the name, like this `osc-js@2.4.1`.
21+
22+
![add npm](img/add_npm.png)
23+
24+
The wanted package will be installed into the [op's directory](../2_sharing_ops/sharing_ops) into a `node_modules` folder.
25+
This folder should not be shared or added to any repositories, as it might contain operating-system dependent code (and
26+
also is usually pretty big...).
27+
28+
Afterward, add the `standalone_electron` core-lib to the Op. This will make sure that people that end up using this
29+
on cables.gl will get a warning that this Op might not work on the web.
30+
31+
![add npm](img/corelib.png)
32+
33+
### I am getting errors like `require() of ES Module` or `failed to load node module`
34+
35+
This likely means that the library/module you are trying to use is either:
36+
37+
- not packaged to be used in electron/browser
38+
- uses native modules that need to be precompiled
39+
40+
You can try working around this by putting the precompiled/packaged node_modules folder into the [op-dir](../2_sharing_ops/sharing_ops) on your own,
41+
but these ops won't be [sharable](../2_sharing_ops/sharing_ops).
42+
43+
### How do I use a library in any of my ops?
44+
45+
After you added the library to your op (say you used the `osc-js`-package from above) you can use `op.require` to load the
46+
library. Here are a few examples from the documentation pages of different libraries and how they translate to cables:
47+
48+
#### require:
49+
```js
50+
const OSC = require('osc-js')
51+
```
52+
will become:
53+
```js
54+
const OSC = op.require("osc-js");
55+
```
56+
---
57+
#### default import:
58+
```js
59+
import path from 'path';
60+
```
61+
will become:
62+
```js
63+
const path = op.require("path");
64+
```
65+
---
66+
#### named import:
67+
```js
68+
import { HfInference } from '@huggingface/inference';
69+
```
70+
will become:
71+
```js
72+
const hf = op.require("@huggingface/inference");
73+
const HfInference = hf.HfInference;
74+
```
75+
76+
## Does cables standalone come with built-in libraries?
77+
78+
Cables standalone comes with (at least) the native [nodejs libraries](https://github.com/nodejs/node/tree/v20.13.1/lib) of the node
79+
version that was used to build it, this (currently) includes modules like `os`, `fs`, `path`, `http`, `net` and more...
80+
81+
You can use these modules without adding them to the dependencies section in "Manage Op":
82+
83+
```js
84+
const OSC = op.require("os");
85+
const ifaces = os.networkInterfaces();
86+
```

‎md/6_2_standalone/4_exporting/exporting.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Import/Export
2+
3+
## Export patch from cables.gl to standalone
4+
5+
Any patch that is exported using the "patch" export option has everything needed (ops, assets, ...) to be opened
6+
in the standalone version. Make sure to have a [recent version](https://cables.gl/standalone) of cables standalone to make sure all the core
7+
ops are up-to-date.
8+
9+
## Export patch from standalone (to cables.gl)
10+
11+
To export a patch that you worked on in cables standalone and put it on a web server, select "Export - HTML" from the
12+
navigation. This will create a ZIP-File that is similar to the [HTML-Export](../../4_export_embed/dev_embed/export_zip/export_zip) on cables.gl
13+
14+
The "Export - Patch" option will give you a zip-file containing an export that is similar to the ["Patch"](../../4_export_embed/dev_embed/export_standalone/export_standalone) export option
15+
on cables.gl and can be imported back to cables.gl using the [ZIP-Upload](https://cables.gl/mydata#import) in "My Data".
16+
17+
![add npm](img/nav.png)
18+
19+
If you do not want to import to cables.gl but want to collect all your assets next to your patch-file (the `.cables` one),
20+
in the standalone version, press `cmd + p` or `ctrl + p` to open up the command palette and execute these two commands:
21+
22+
![add npm](img/copy_ops.png)
23+
24+
25+

‎md/6_2_standalone/4_exporting/img/copy_ops.png

15.6 KB
Loading

‎md/6_2_standalone/4_exporting/img/nav.png

11.9 KB
Loading

‎md/6_2_standalone/5_standalone_faq/standalone_faq.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Standalone - FAQ
2+
3+
## Where can I find more information and tutorials to get started?
4+
5+
There are plenty of tutorial videos on our [YouTube channel](https://www.youtube.com/cables_gl), some cover specific standalone topics. Feel free to suggest
6+
topics, if you think something is missing or subscribe to the channel to get notified once we add a new video.
7+
8+
## I am having issues playing videos in cables standalone
9+
10+
Most of the videos around should play fine. If you encounter error-messages containing "ffmpg" that video format is likely
11+
not supported by cables, electron and/or your operating system. This then is an issue with proprietary video codecs, and
12+
we cannot really do anything about that...sorry...
13+
14+
## I get weird results when using filenames or file system-paths across operating systems
15+
16+
As a general rule of thumb: Whenever cables uses files, it's using URLs. URLs of local files look like this:
17+
18+
`file:/home/cables/myfile.txt` or `file:/C:/Users/cables/myfile.txt`
19+
20+
Notice the forward slashes. To keep this OS-independent, whenever you deal with files, try to use file-url.
21+
There are ops to convert [back](https://cables.gl/op/Ops.Extension.Standalone.Files.PathToFileUrl) and [forth](https://cables.gl/op/Ops.Extension.Standalone.Files.PathToFileUrl) between URLs and paths.
22+
23+
## How can I support the development of cables and the standalone version?
24+
25+
Most definitely, check out the general section on [supporting cables](../../faq/faq) . Thank you!

‎md/6_2_standalone/standalone.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Cables Standalone
2+
3+
__TOC__

‎md/faq/features/contribute/contribute.md

+6-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,12 @@ The easiest way to contribute this to the community is to [create a team](https:
1010

1111
---
1212

13-
For bugfixes or improvements in core ops, the editor or the standalone version, read up on how to [develop cables](../../../6_1_developing_cables/developing_cables)
13+
If it's a really small fix, you can create a pull-request directly in github. Check out the [YouTube-Video](https://www.youtube.com/watch?v=V4Wc5JwZWaU) on how to
14+
quickly contribute to the cables documentation, for an example.
15+
16+
---
17+
18+
For more complex bugfixes or improvements in core ops, the editor or the standalone version, read up on how to [develop cables](../../../6_1_developing_cables/developing_cables)
1419
and create a pull request for the affected repository.
1520

1621
Thanks for contributing!

‎md/faq/features/reports/reports.md

+42-42
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,42 @@
1-
# How to report a bug in cables
2-
3-
As cables is in constant development, there will be bugs here and there. We also try to keep our documentation and examples up-to-date but when you notice things not working the way they are described or you expected - Please submit an issue for us following the guidelines below!
4-
5-
6-
## Where to report bugs?
7-
8-
Please keep all bugreports to the [Discussions forum](https://github.com/cables-gl/cables_docs/discussions/categories/bug-reports) .
9-
Check out previously submitted bugs first and if you find a related report, vote it up and post about your findings too. That way we have more details and can see how frequently this bug happens!
10-
11-
## What information to include in my post to GitHub Discussions?
12-
13-
### Description of your environment
14-
15-
First and foremost - tell us what operating system and browser your are using.
16-
Send us the generated link provided on [cables.gl/browser](https://cables.gl/browser) - it will be on top of the page.
17-
18-
Tell us more about your project and how it is running - on mobile? on WordPress? inside the cables.gl editor?
19-
20-
### A simple step by step explanation that is reproducible
21-
22-
Please include a simple explanation that is showing your issue as isolated as possible.
23-
24-
Attaching a video and screenshot illustrating your issue is great too.
25-
26-
### A small and simple example patch
27-
28-
Please try to isolate the problem and provide a simple example patch that displays what
29-
is going wrong. Provide us with a link in your issue post!
30-
31-
### A screenshot of your browsers dev-console
32-
33-
For most browsers you can open the dev-console by rightclicking anywhere on the page, selecting "inspect element"
34-
and then switching to the console tab. Keep the console open and reproduce the error in your patch. Please provide a screenshot of the errors reported in the console.
35-
36-
This is a bit harder to do on a mobile-phone, but if you are used to remote-debugging android/ios-devices
37-
a glimpse into your dev-console would help here also.
38-
39-
40-
## I have code that fixes the issue!
41-
42-
Awesome! Please post your findings on our [Discussions forum](https://github.com/cables-gl/cables_docs/discussions/categories/bug-reports) and provide your proposed fixes and solutions. We highly appreciate contributors and community members that go above and beyond. Thanks for contributing and expect a token of our thanks in the mail!
1+
# How to report a bug in cables
2+
3+
As cables is in constant development, there will be bugs here and there. We also try to keep our documentation and examples up-to-date but when you notice things not working the way they are described or you expected - Please submit an issue for us following the guidelines below!
4+
5+
6+
## Where to report bugs?
7+
8+
Please keep all bugreports to the [Discussions forum](https://github.com/cables-gl/cables_docs/discussions/categories/bug-reports) .
9+
Check out previously submitted bugs first and if you find a related report, vote it up and post about your findings too. That way we have more details and can see how frequently this bug happens!
10+
11+
## What information to include in my post to GitHub Discussions?
12+
13+
### Description of your environment
14+
15+
First and foremost - tell us what operating system and browser your are using.
16+
Send us the generated link provided on [cables.gl/browser](https://cables.gl/browser) - it will be on top of the page.
17+
18+
Tell us more about your project and how it is running - on mobile? on WordPress? inside the cables.gl editor?
19+
20+
### A simple step by step explanation that is reproducible
21+
22+
Please include a simple explanation that is showing your issue as isolated as possible.
23+
24+
Attaching a video and screenshot illustrating your issue is great too.
25+
26+
### A small and simple example patch
27+
28+
Please try to isolate the problem and provide a simple example patch that displays what
29+
is going wrong. Provide us with a link in your issue post!
30+
31+
### A screenshot of your browsers dev-console
32+
33+
For most browsers you can open the dev-console by rightclicking anywhere on the page, selecting "inspect element"
34+
and then switching to the console tab. Keep the console open and reproduce the error in your patch. Please provide a screenshot of the errors reported in the console.
35+
36+
This is a bit harder to do on a mobile-phone, but if you are used to remote-debugging android/ios-devices
37+
a glimpse into your dev-console would help here also.
38+
39+
40+
## I have code that fixes the issue!
41+
42+
Awesome! Please post your findings on our [Discussions forum](https://github.com/cables-gl/cables_docs/discussions/categories/bug-reports) and provide your proposed fixes and solutions. We highly appreciate contributors and community members that go above and beyond. Thanks for contributing and expect a token of our thanks in the mail!

0 commit comments

Comments
 (0)