diff --git a/website/public/dependencygraph.svg b/website/public/dependencygraph.svg new file mode 100644 index 00000000..62fadac7 --- /dev/null +++ b/website/public/dependencygraph.svg @@ -0,0 +1,326 @@ + + + + + + + + +@strudel.cycles/core@0.6.8 + +@strudel.cycles/core@0.6.8 + + + +fraction.js@4.2.0 + +fraction.js@4.2.0 + + + + + +@strudel.cycles/csound@0.6.2 + +@strudel.cycles/csound@0.6.2 + + + + + +@strudel.cycles/webaudio@0.6.1 + +@strudel.cycles/webaudio@0.6.1 + + + + + + + + + +@strudel.cycles/embed@0.2.0 + +@strudel.cycles/embed@0.2.0 + + + +@strudel.cycles/midi@0.6.0 + +@strudel.cycles/midi@0.6.0 + + + + + +@strudel.cycles/webaudio@0.6.0 + +@strudel.cycles/webaudio@0.6.0 + + + + + + + + + +@strudel.cycles/mini@0.6.0 + +@strudel.cycles/mini@0.6.0 + + + + + +@strudel.cycles/osc@0.6.0 + +@strudel.cycles/osc@0.6.0 + + + + + + + + + + + +@strudel.cycles/serial@0.6.0 + +@strudel.cycles/serial@0.6.0 + + + + + +@strudel.cycles/soundfonts@0.6.0 + +@strudel.cycles/soundfonts@0.6.0 + + + + + + + +sfumato@0.1.2 + +sfumato@0.1.2 + + + + + +soundfont2@0.4.0 + +soundfont2@0.4.0 + + + + + +@strudel.cycles/tonal@0.6.0 + +@strudel.cycles/tonal@0.6.0 + + + + + + + + + +chord-voicings@0.0.1 + +chord-voicings@0.0.1 + + + + + + + +@strudel.cycles/transpiler@0.6.0 + +@strudel.cycles/transpiler@0.6.0 + + + + + + + + + + + + + + + + + + + +@strudel.cycles/xen@0.6.0 + +@strudel.cycles/xen@0.6.0 + + + + + + + +chord-voicings@0.0.1->@tonaljs/tonal@4.10.0 + + + + + +sfumato@0.1.2->soundfont2@0.4.0 + + + + +@strudel.cycles/core@0.6.8->fraction.js@4.2.0 + + + +@strudel.cycles/csound@0.6.2->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/csound@0.6.2->@strudel.cycles/webaudio@0.6.1 + + + +@strudel.cycles/midi@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/midi@0.6.0->@strudel.cycles/webaudio@0.6.0 + + + +@strudel.cycles/midi@0.6.0->webmidi@3.1.4 + + + +@strudel.cycles/mini@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/osc@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/osc@0.6.0->osc-js@2.4.0 + + + +@strudel.cycles/serial@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/soundfonts@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/soundfonts@0.6.0->@strudel.cycles/webaudio@0.6.0 + + + +@strudel.cycles/soundfonts@0.6.0->sfumato@0.1.2 + + + +@strudel.cycles/soundfonts@0.6.0->soundfont2@0.4.0 + + + +@strudel.cycles/tonal@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/tonal@0.6.0->@tonaljs/tonal@4.10.0 + + + +@strudel.cycles/tonal@0.6.0->chord-voicings@0.0.1 + + + +@strudel.cycles/tonal@0.6.0->webmidi@3.1.4 + + + +@strudel.cycles/transpiler@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/transpiler@0.6.0->acorn@8.8.2 + + + +@strudel.cycles/transpiler@0.6.0->escodegen@2.0.0 + + + +@strudel.cycles/transpiler@0.6.0->estree-walker@3.0.3 + + + +@strudel.cycles/webaudio@0.6.1->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/xen@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/webaudio@0.6.0->@strudel.cycles/core@0.6.8 + + + +@strudel.cycles/csound@0.6.2->@csound/browser@6.18.5 + + + + \ No newline at end of file diff --git a/website/public/pwa/strudel-linux.png b/website/public/pwa/strudel-linux.png new file mode 100644 index 00000000..b60edf70 Binary files /dev/null and b/website/public/pwa/strudel-linux.png differ diff --git a/website/public/pwa/strudel-macos.png b/website/public/pwa/strudel-macos.png new file mode 100644 index 00000000..cb907d16 Binary files /dev/null and b/website/public/pwa/strudel-macos.png differ diff --git a/website/src/config.ts b/website/src/config.ts index 26273dba..f8585be1 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -73,9 +73,9 @@ export const SIDEBAR: Sidebar = { ], Development: [ { text: 'REPL', link: 'technical-manual/repl' }, + { text: 'Packages', link: 'technical-manual/packages' }, { text: 'Docs', link: 'technical-manual/docs' }, { text: 'Testing', link: 'technical-manual/testing' }, - // { text: 'Packages', link: 'technical-manual/packages' }, // { text: 'Internals', link: 'technical-manual/internals' }, ], }, diff --git a/website/src/pages/learn/pwa.mdx b/website/src/pages/learn/pwa.mdx index 29c0843b..b7514766 100644 --- a/website/src/pages/learn/pwa.mdx +++ b/website/src/pages/learn/pwa.mdx @@ -7,5 +7,79 @@ layout: ../../layouts/MainLayout.astro You can use Strudel even without a network! When you first visit the [Strudel REPL](strudel.tidalcycles.org/), your browser will download the whole web app including documentation. +When the download is finished (<1MB), you can visit the website even when offline, +getting the downloaded website instead of the online one. + +When the site gets updated, your browser will download that update on the next online visit. +When an update is available, the site will refresh after the download is finished. + +This works because Strudel is implemented as progessive web app (using [Vite PWA](https://vite-pwa-org.netlify.app/)). + +## Samples + +While the browser will download the app itself, samples are only downloaded when you're actively using them. +So to make sure a specific set of samples is available when offline, just use them. +Also, only samples from these domains will be cached for offline use: + +- `https://raw.githubusercontent.com/*` for samples uploaded to github +- `https://freesound.org/*` / `https://cdn.freesound.org/*` for freesound +- `https://shabda.ndre.gr/.*` for shabda + +## Inspecting / Clearing Cache + +You can view all cached files in your browser. + +### Firefox + +- Open the Developer Tools (`Tools > Web Developer > Web Developer Tools`) +- go to `Storage` tab and expand `Cache Storage > https://strudel.tidalcycles.org`. +- or go to the `Application` tab and view the latest updates in `Service Workers` + +### Chromium based Browsers + +- Open Developer Tools (`Right Click > Inspect`) +- go to the `Application` tab +- view downloaded files under `Cache > Cache Storage` +- view the latest updates in `Service Workers` + +## Strudel Standalone App + +You can also install Strudel as a standalone app on most devices. +A standalone app has its own desktop / homescreen icon and launches in a separate window, +without the browser ui. + +
+ Strudel on MacOS +
Strudel on MacOS
+
+ +### Desktop + +With a chromium based browser: + +1. go to the [Strudel REPL](strudel.tidalcycles.org/). +2. on the right of the adress bar, click `install Strudel REPL` +3. the REPL should now run as a standalone chromium app + +Without a chromium based browser, you can use [nativefier](https://github.com/nativefier/nativefier) to generate a desktop app: + +1. make sure you have NodeJS installed +2. run `npx nativefier strudel.tidalcycles.org` + +
+ Strudel on Linux +
Strudel on Linux
+
+ +### iOS + +1. open to the [Strudel REPL](strudel.tidalcycles.org/) in safari +2. press the share icon and tab `Add to homescreen` +3. You should now have a strudel app icon that opens the repl in full screen + +### Android + +1. open to the [Strudel REPL](strudel.tidalcycles.org/) +2. Tab the install button at the bottom Ok, what are [Patterns](/technical-manual/patterns) all about? diff --git a/website/src/pages/technical-manual/packages.mdx b/website/src/pages/technical-manual/packages.mdx index 974b9f43..9efd351b 100644 --- a/website/src/pages/technical-manual/packages.mdx +++ b/website/src/pages/technical-manual/packages.mdx @@ -5,75 +5,58 @@ layout: ../../layouts/MainLayout.astro import { MiniRepl } from '../../docs/MiniRepl'; -## Strudel Packages +# Strudel Packages -The [strudel repo](github.com/tidalcycles/strudel) is organized into packages, using [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces). -Publishing packages is done with [lerna](https://lerna.js.org/). +The [strudel repo](github.com/tidalcycles/strudel) is organized as a monorepo, containing multiple npm packages. +The purpose of the multiple packages is to -There are different packages for different purposes. They.. +- organize the codebase into more modular, encapsulated pieces +- be able to opt out of certain functionalities +- keep the dependencies of the core packages small -- split up the code into smaller chunks -- can be selectively used to implement some sort of time based system +## Overview [See the latest published packages on npm](https://www.npmjs.com/search?q=%40strudel.cycles). +Here is an overview of all the packages: -### Important bits +### Essential Packages -- The [root package.json](https://github.com/tidalcycles/strudel/blob/main/package.json) specifies `packages/*` as `workspaces` -- Each folder in `packages` comes with its own `package.json`, defining a package name of the format `@strudel.cycles/` -- Running `npm i` from the root folder will symlink all packages to the `node_modules` folder, e.g. `node_modules/@strudel.cycles/core` symlinks `packages/core` -- These symlinks allow importing the packages with their package name, instead of a relative path, e.g. `import { seq } from '@strudel.cycles/core'`, instead of `import { seq } from '../core/`. - This works because the [bare module import](https://vitejs.dev/guide/features.html#npm-dependency-resolving-and-pre-bundling) `@strudel.cycles/core` is resolved to `node_modules/@strudel.cycles/core`. - In a project that installs the published packages from npm, these imports will still work, whereas relative ones might not. -- When a strudel package is importing from another strudel package, the package that is imported from should be listed in the `dependencies` field of the `package.json`. - For example, [@strudel.cycles/mini lists `@strudel.cycles/core` as a dependency](https://github.com/tidalcycles/strudel/blob/main/packages/mini/package.json). -- In development, files in any package can be changed and saved to instantly update the dev server via [hot module replacement](https://vitejs.dev/guide/features.html#hot-module-replacement) -- To publish packages, `npx lerna publish` will check which packages were changed since the last publish and publish only those. - The version numbers in the dependencies of each packages will be updated automatically to the latest version. +These package are the most essential. You might want to use all of those if you're using strudel in your project: -### Building & Publishing +- [core](https://github.com/tidalcycles/strudel/tree/main/packages/core#strudelcyclescore): tidal pattern engine with core primitives +- [mini](https://github.com/tidalcycles/strudel/tree/main/packages/mini#strudelcyclesmini): mini notation parser + core bindings +- [transpiler](https://github.com/tidalcycles/strudel/tree/main/packages/transpiler#strudelcyclestranspiler): user code transpiler. syntax sugar + highlighting -Currently, all packages are only published as ESM with vite flavour. -To build standardized ESM and CJS files, a `vite.config.js` like that is needed: +### Language Extensions -```js -import { defineConfig } from 'vite'; -import { dependencies } from './package.json'; -import { resolve } from 'path'; +These packages extend the pattern language by specific functions -// https://vitejs.dev/config/ -export default defineConfig({ - plugins: [], - build: { - lib: { - entry: resolve(__dirname, 'index.mjs'), - formats: ['es', 'cjs'], - fileName: (ext) => ({ es: 'index.mjs', cjs: 'index.js' }[ext]), - }, - rollupOptions: { - external: [...Object.keys(dependencies)], - }, - target: 'esnext', - }, -}); -``` +- [tonal](https://github.com/tidalcycles/strudel/tree/main/packages/tonal): tonal functions for scales and chords +- [xen](https://github.com/tidalcycles/strudel/tree/main/packages/xen): microtonal / xenharmonic functions -This will build `index.mjs` (ESM) and `index.js` (CJS) to the dist folder. +### Outputs -### What's the main file? +These packages provide bindings for different ways to output strudel patterns: -Currently, each package uses the unbundled `index.mjs` as its main file, which must change for the published version. -There are 2 ways to handle this: +- [webaudio](https://github.com/tidalcycles/strudel/tree/main/packages/webaudio#strudelcycleswebaudio): the default webaudio output +- [osc](https://github.com/tidalcycles/strudel/tree/main/packages/osc#strudelcyclesosc): bindings to communicate via OSC +- [midi](https://github.com/tidalcycles/strudel/tree/main/packages/midi#strudelcyclesmidi): webmidi bindings +- [csound](https://github.com/tidalcycles/strudel/tree/main/packages/csound#strudelcyclescsound): csound bindings +- [soundfonts](https://github.com/tidalcycles/strudel/tree/main/packages/serial#strudelcyclessoundfonts): Soundfont support +- [serial](https://github.com/tidalcycles/strudel/tree/main/packages/serial#strudelcyclesserial): webserial bindings -1. `main` = `dist/index.js`, `module` = `dist/index.mjs`. The built files are used. This means that changing a source file won't take effect in the dev server without a rebuild. -2. Use different `package.json` files for dev vs publish. So the unbuilt `index.mjs` could be used in dev, while the built files can be used when publishing. +### Others -Option 1 could be done with [workspace watching](https://lerna.js.org/docs/features/workspace-watching), although it might make the dev server less snappy.. -Option 2 can be done by [publishing just the dist folder and copying over the `package.json` file](https://stackoverflow.com/questions/37862712/how-to-publish-contents-only-of-a-specific-folder). -Sadly, [this does not fit into how lerna works](https://github.com/lerna/lerna/issues/91). +- [embed](https://github.com/tidalcycles/strudel/tree/main/packages/embed#strudelcyclesembed): embeddable REPL web component +- [react](https://github.com/tidalcycles/strudel/tree/main/packages/react#strudelcyclesreact): react hooks and components for strudel -https://github.com/changesets/changesets +### No Longer Maintained -https://turbo.build/repo/docs/handbook/publishing-packages/versioning-and-publishing +- [eval](https://github.com/tidalcycles/strudel/tree/main/packages/eval): old code transpiler +- [tone](https://github.com/tidalcycles/strudel/tree/main/packages/tone#strudelcyclestone): bindings for Tone.js instruments and effects +- [webdirt](https://github.com/tidalcycles/strudel/tree/main/packages/webdirt): webdirt bindings, replaced by webaudio package -https://pnpm.io/workspaces +## Tools + +- [pnpm workspaces](https://pnpm.io/) +- Publishing packages is done with [lerna](https://lerna.js.org/).