Merge pull request #193 from dascritch/preprod

Release 7.1

CONTRIBUTING.md

@@ -7,10 +7,6 @@ If you are not a developer
  - You may be have a disability and you're using some accessibility tools… You're super useful ! For sure, I missed something important for you.
  - Perhaps you can help me on translations, the design or the logos.
  - Install in your own website, test, note the bugs, [report them in the issues section of the repo](https://github.com/dascritch/cpu-audio/issues). If you're not enough GitHub savvy, you can [write me via this page](https://cpu.dascritch.net/pages/CPU-Audio-Player)
- - If you can, test on your computer with a local server. In a shell opened in the directory of cpu-audio code :
- 	- PHP (for local testing) : `php -S 0.0.0.0:8000`
- 	- Node.js : `npx http-server .`
- 	- Python : `python -m http.server`  (check your python version, 3+)
 
 
 If you are a developer
@@ -26,6 +22,10 @@ If you are a developer
  - Document everything, even dead-ends. Someone can find interesting your regrets.
  - Work by cloning the `preprod` branch. We merge in `master` when everything is alright.
  - Check first in [TODO.md](TODO.md) which lists some priorities and objectives. I usually [create bugs](https://github.com/dascritch/cpu-audio/issues) and refers to them in my commits. Most of the time.
+ - If you can, test on your computer with a local server. In a shell opened in the directory of cpu-audio code :
+ 	- PHP (for local testing) : `php -S 0.0.0.0:8000`
+ 	- Node.js : `npx http-server .`
+ 	- Python : `python -m http.server`  (check your python version, 3+)
  - Node.js 14 is mandatory to run CLI tests with modules.
  - Most of functions and methods are now javadoc-style commented, be kind about it.
 
@@ -60,6 +60,7 @@ Those tests [can be run from our mini-site](https://dascritch.github.io/cpu-audi
 
 Please note that tests aren't done yet on non-default themes.
 
+
 Development
 -----------
 
@@ -70,3 +71,20 @@ You will need to add packages via `npm install` to finalize `build/*` files.
 If you're not working on `master` or `preprod` original branches, try to avoid to commit `build/*` files, to avoid conflicts during merge.
 
 The cleanest way to make files for a new release is `./make.sh --clean --all-themes --test --index`
+
+
+Code acceptability
+------------------
+
+ - Respect of standards
+ - Simplicity
+ - Atomicity
+ - Re-usability
+ - Tests
+ - In code documentation (function annotations, etc…)
+ - Documentation
+ - Examples
+ - Parametrable thru [`live_config`](applications/live_config.html)
+
+Some of the ballot-box won't apply on your patch, and you may need help to fullfill some of them. We can help you, the goal is to learn together and understand good practices and standards.
+

EXAMPLES.md

@@ -31,3 +31,4 @@
  * [tests/tests-controller.html](tests/tests-controller.html)
  * [tests/tests-interface.html](tests/tests-interface.html)
  * [tests/tests-minimal.html](tests/tests-minimal.html)
+ * [tests/tests-parameters.html](tests/tests-parameters.html)

FAQ.md

@@ -16,13 +16,13 @@ In fact, the basis of cpu-audio.js are back from 2010, from my previous radio sh
 Why using URL ?
 ---------------
 
-**Because URL is a standard**, actually mesestimated. But it's universal, accessible, portable, for both local and internet usage. I wish people will start pointing some moment in an audio content of a webpage by giving a standard URL with a timecode in it.
+**Because URL is a standard**, actually mesestimated. But it's universal, accessible, portable, for both local and internet usage. And there is [a W3C standard for pointing geometric or timestamp position : Media Fragments](https://www.w3.org/TR/media-frags/). I wish people will start pointing some moment in an audio content of a webpage by giving a standard URL with a timecode in it.
 
 
 Why have you done (x) choice ?
 ------------------------------
 
-May be [I've written about it on my blog.](https://www.w3.org/TR/media-frags/) But It's in French. What is really fun with the web is the ability to remix webpages contents, so you can use any translator on it.
+May be [I've written about it on my blog.](https://dascritch.net/post/2018/11/06/Reconstruire-son-lecteur-audio-pour-le-web) But It's in French. What is really fun with the web is the ability to remix webpages contents, so you can use any translator on it.
 
 May be I didn't explained what is interesting you. Write me, I'll respond.
 
@@ -32,15 +32,15 @@ Is it GDPR compliant ?
 
 **Yes.** 
 
-cpu-audio is storing curently playing audio source and position, in order to set the same playing audio at the exact same position later. But that data is stored only in the client browser, is not nominative and never transmitted to a third-part service.
+cpu-audio is storing currently playing audio source and position, in order to set the same playing audio at the exact same position later. But that data is stored only in the client browser, is not nominative and never transmitted to a third-part service.
 
-As I was involved to GDPR compliance in my day job and co-hosting some cryptoparties, It is an important point for me.
+As I was involved to GDPR compliance in my day job and co-hosting some cryptoparties, this is an important point for me.
 
 
 The player is ugly
 ------------------
 
-Yes ! It is only a proof of concept and I'm only a coder. **That why version 7 sports a theme system.** I'm sure someone will do a very better looking one than mine !
+I agree. It is only a proof of concept and I'm only a coder. **That why version 7 sports a theme system.** I'm sure someone will do a very better looking one than mine !
 
 If you wish to participate to this project, please have a look to [CONTRIBUTING.md](CONTRIBUTING.md).
 
@@ -50,11 +50,11 @@ You're talking about SoundCloud in some code comments and tickets
 
 **It's true.**
 
-I'm piss of that musicians, benevolent radio producers and community reporters are using SoundCloud or (even worst) MixCloud. Why don't they are opening their websites with their graphical universe and without profiling web habits from their fans ?
+I'm piss of that musicians, benevolent radio producers and community reporters are using SoundCloud or (even worst) MixCloud. Why don't they are opening their websites with their graphical universe and without tracking web habits from their fans ?
 
 The main issue was commenting on some time points to engage their community. At this moment, Mastodon didn't start but we already have its decentralized system, and there also was a W3C standard written for comments in a webpage.
 
-At the beginning of version 3, we were also thinking about a really decentralized playlist system : The user should have a WebExtension companion, and can select some sounds among surfing.
+At the beginning of version 3, we were also thinking about a really decentralized playlist system : The user may have a WebExtension companion, and can select some sounds among surfing.
 
 **It's up to you** to make those projects alive ! See ([#8](#8)), ([#10](#10)), and ([#76](#76))
 

INSTALL.md

@@ -43,7 +43,7 @@ A more elaborated example :
 
 * Put one and only one `<audio>` tag into `<cpu-audio>`, or you may have unexpected issues.
 * **We recommend to set an `id` attribute** to the `<audio>` tag for the anchoring feature, elsewhere cpu-audio.js will autoset an `id`, that may cause later some problems for deep-linking sound into your page or your web-app. Please set an ID to the `<audio>` tag by yourself.
-* You **must** put a `controls` attribute to the included `<audio>` tag ; this is a good practice for having a functional fallback in case of malfunction, we wish you to comply. Please also add this rule in your css, even if our included css will put it :
+* You **must** put a `controls` attribute to the included `<audio>` tag ; this is a good practice for having a functional fallback in case of malfunction ; we wish you to comply. Please also add this rule in your css, even if our included css will put it :
 
 ```css
 audio[controls] {
@@ -200,6 +200,7 @@ Here is the `<source data-downloadable>` method. It is recommended for dynamic s
 
 Note that we have [a code snippet extending this attribute for displaying multiple choices to the visitor](examples/API_insert_downloadables_panel.html)
 
+
 Special case for live streamed media
 ------------------------------------
 
@@ -265,6 +266,7 @@ Some color/background values are not recommended, as `currentColor` and `transpa
 
 In case you need to create some specific breakpoints, the best way is to create a theme and make your own version. See [API.md](https://github.com/dascritch/cpu-audio/blob/master/API.md) and [CONTRIBUTING.md](https://github.com/dascritch/cpu-audio/blob/master/CONTRIBUTING.md).
 
+
 Using classes on host page
 --------------------------
 
@@ -314,6 +316,39 @@ The `<audio id="audiotag_id">` is actually playing the `cue_id` chapter. The `cu
 This function was meant to build effects as in [BBC Computer Literacy archive](https://computer-literacy-project.pilots.bbcconnectedstudio.co.uk/) : During a play of a show, each chapter was highlighting its text resumee.
 
 
+Setting global application parameters via a tag
+-----------------------------------------------
+
+Some global parameters for CPU-Audio may be set via a tag, avoiding to write javascript code for the same result. Those prameters must be set in a JSON form (non-nested object), into a `<script type="application/json" data-cpu-audio>` tag set statically in the `<head>` of the document. Beware to set this tag _before_ then `<script>` calling (or including) cpu-audio.js . Here is an example, modifying the playing stoping others players behaviour :
+
+```html
+<head>
+[…]
+	<script type="application/json" data-cpu-audio>
+		{ "playStopOthers" : false }
+	</script>
+	<script src="cpu-audio.js" async></script>
+```
+
+Here are those parameters, usage and default values :
+
+name (case sensitive)    | default value      | usage
+-------------------------|--------------------|----------
+`playStopOthers`         | `true`             | When a `<cpu-audio>` starts to play, any other instances in the same page are paused.
+`scrollTo`               | `false`            | On any link to a time-stamp in the page, will scroll the viewport to display the playing interface.
+`autoplay`               | `false`            | Will try to play at the start of the page if a temporal url is given or the audio was previously exited. This may be prevented by your browser.
+`IDPrefix`               | `"CPU-Audio-tag-"` | Prefix for auto-attributed ID to `<audio>` element without `id=` attribute.
+`globalCss`	             | `true`             | Insert in the `<head>` of the host document a specific `<style>` with all needed css variables for the player.
+`advanceInPlaylist`      | `true`             | When an audio is ended in a playlist, starts immediatly the next one.
+`keymove`                | `5`                | Number of seconds skipped in the timeline when <kbd>←</kbd> or <kbd>→</kbd> keys are pressed in an interface
+`alternateDelay`         | `1000`             | Delay for a long press on time-line (in milliseconds) to switch to the handheld alternate browsing interface. Not recommended to modify.
+`fastFactor`             | `4`                | Amplification ratio between <kbd>▸︎▸︎</kbd> and <kbd>▸︎▸︎▸︎</kbd> in handheld alternate browsing interface
+`repeatDelay`            | `400`              | First repetition delay when clicking a button in handheld alternate browsing interface
+`repeatFactor`           | `100`              | Next repetitions delay when clicking a button in handheld alternate browsing interface
+
+Those parameters may also be changed via javascript, see the [API.md](API.md) page, *document.CPU* chapter
+
+
 Using javascript API
 --------------------
 

RELEASE.md

@@ -1,5 +1,34 @@
+RELEASE NOTES version 7.1
+=========================
+
+
+New features
+------------
+
+* You can set some global parameters via a `<script data-cpu-audio>` tag in the `<head>` of the host page ([#185](#185))
+* Can scroll the viewport of the page on the player when clicking on a temporal link. Parametrable setting ([#60](#60))
+* Being able to not include global.css on host page ([#181](#181))
+* Automated ID prefix for not identified `<audio>` is now parametrable ([#186](#186))
+
+Corrections
+-----------
+
+* Hash parameters are now case insensitive
+* Instanciation may be missed during the page lifecyle. Better way to check if host page DOM is really ready or not
+* Application chapters_builder should stop zero-ing time input in some situations
+* Better style on focused `<summary>`
+* Do not insert global `<style>` in page if webcomponent is not supported by the browser (I know, this is a late situation)
+
+Back-end
+--------
+
+* Node 18 support for build (incomplete)
+* Locales are modularized : each language has its own file, in `src/locales` ([#189](#189))
+* Some libs moved in `./src` sub-directories, big sources were splitted in functionnality segments.
+
+
 RELEASE NOTES version 7.0.3
-======================
+===========================
 
 New features
 ------------

TODO.md

@@ -4,20 +4,22 @@ TO DO list
 For release 7.1
 ---------------
 
- - On-the-fly generated spectrogram, as add-on and on the chapters_editor ([#117](#117))
  - Focus outline of WebComponent on Safari ([#151](#151))
- - Aria roles on fine position buttons
- - [Automated example page generated for each theme from make.sh #124](#124)
+ - Aria roles on fine position buttons ([#188](#188)) and on progress bar ([#145](#145))
  - Full test comparing campaign of all available platforms ([#138](#138)), ([#113](#113))
- - Udpate dotclear addon companion ([#67](#67))
  - Resolve failing test only on Chrome Android ([#121](#121)) may be linked to event engine on this very specific software
- - Resolve specific autostart issue on Safari iPhone #149
+ - Resolve specific autostart issue on Safari iPhone ([#149](#149))
+ - Natural static panel with html direct inclusion ([#173](#173))
+ - Scroll viewport to the audio element ([#60](#60))
+ - Panels order ([#123](#123))
+ - Being able to not include global.css on host page ([#181](#181))
+ - Make parametrables auto-id prefix ([#186](#186))
+ - If not existing, automated example page generated for each theme from make.sh ([#124](#124))
+ - Udpate dotclear addon companion ([#67](#67))
 
 Planned evolutions
 ------------------
 
-- [ ] Standards first
-    - [ ] use standard [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) in `hashOrder`, instead of the custom code. We need a strategy to get the anchor, seen as a key without value
 - [ ] add-ons packages
     - [ ] wordpress
 - [ ] `<video>` support
@@ -28,5 +30,4 @@ Planned evolutions
     - [ ] [Supporting annotations à la SoundCloud](https://github.com/dascritch/cpu-audio/issues/10)
 - [ ] [Prepare design and key bindings for RTL localizations](https://github.com/dascritch/cpu-audio/issues/26)
 - [ ] Propose a code snippet in `examples/` to do a `ticker` plane track mode
-- [ ] Example add-on with FFT analyzer, like in [webcammictester](https://webcammictest.com/check-mic.html)
-
+- [ ] Example add-on with FFT analyzer, like in [webcammictester](https://webcammictest.com/check-mic.html). On-the-fly generated spectrogram, as add-on and on the chapters_editor ([#117](#117))

applications/chapters_editor.js

@@ -3,7 +3,7 @@
 let sound_element, component_element, list_element, edit_source_audio_element, edit_source_webvtt_element;
 let sound_CPU;
 let line_number = 1;
-let convert = document.CPU;
+let convert = null;
 
 const point_canvas = {
             text : '',
@@ -33,6 +33,9 @@ function normalize_time(currentTime) {
     if ((currentTime === '') || (!currentTime)) {
         return null;
     }
+    if (typeof currentTime === 'string') {
+    	currentTime = convert.timeInSeconds(currentTime);
+    }
     return Math.abs(Math.floor(Number(currentTime)));
 }
 
@@ -67,8 +70,8 @@ function histogram() {
     let source = audioCtx.createMediaElementSource(sound_element);
     let analyser = audioCtx.createAnalyser();
     analyser.fftSize = 32;
-    let WIDTH = 2000;
-    let HEIGHT = 32;
+    const WIDTH = 2000;
+    const HEIGHT = 32;
     let canvas = document.createElement('canvas');
     canvas.width = WIDTH;
     canvas.height = HEIGHT;