Merge pull request #15 from ImSkully/dev

v1.0.2 Release

.github/workflows/deno-deploy.yml

@@ -0,0 +1,34 @@
+name: Deploy
+on:
+  push:
+    branches: master
+  pull_request:
+    branches: master
+
+jobs:
+  deploy:
+    name: Deploy Application
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+
+      - name: Install Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Build Step
+        run: "deno task build"
+
+      - name: Upload to Deno Deploy
+        uses: denoland/deployctl@v1
+        with:
+          project: ${{ secrets.DENO_DEPLOY_PROJECT }}
+          entrypoint: main.ts
+          exclude: node_modules

.gitignore

@@ -1 +1,8 @@
-node_modules/*
+# Environment files.
+.env
+
+# Fresh build directory.
+_fresh/
+
+# npm dependencies.
+node_modules/

.vscode/extensions.json

@@ -1,8 +1,5 @@
 {
 	"recommendations": [
-		"formulahendry.auto-close-tag",
-		"formulahendry.auto-complete-tag",
-		"formulahendry.auto-rename-tag",
-		"esbenp.prettier-vscode"
+		"denoland.vscode-deno"
 	]
 }

.vscode/settings.json

@@ -1,11 +1,21 @@
 {
 	"editor.formatOnSave": true,
-	"editor.codeActionsOnSave": {
-		"source.fixAll.eslint": "explicit"
+	"deno.enable": true,
+	"deno.lint": true,
+	"editor.defaultFormatter": "denoland.vscode-deno",
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
 	},
-	"editor.tabSize": 4,
-	"editor.insertSpaces": false,
-	"[html]": {
-		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	"[typescript]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
+	},
+	"[javascriptreact]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
+	},
+	"[json]": {
+		"editor.defaultFormatter": "denoland.vscode-deno"
 	}
 }

README.md

@@ -1,83 +1,99 @@
-<div align="center">
-	<img width="200" height="200" src="src/images/rtttl_icon_400px.png" alt="RTTTL Composer Logo">
-	<h2>RTTTL Web Composer</h2>
-</div>
+<p align="center">
+	<a href="https://rtttl.skully.tech" target="_blank">
+		<picture>
+			<img width="150" height="150" src="./static/images/logos/logo_400px.png" alt="RTTTL Web Composer Logo">
+		</picture>
+	</a>
+</p>
+<h1 align="center">
+	RTTTL Web Composer
+</h1>
 
+<p align="center">
+	<img alt="Deno Badge" src="https://img.shields.io/badge/Deno-js?style=flat&logo=deno&logoColor=white&color=black&link=https%3A%2F%2Fdeno.com" />
+	<img alt="Deno Fresh Badge" src="https://img.shields.io/badge/Fresh-js?style=flat&logo=fresh&logoColor=yellow&color=black&link=https%3A%2F%2Ffresh.deno.dev" />
+</p>
 <p align="center">
 	<a href="./LICENSE" alt="Project License"><img src="https://img.shields.io/github/license/ImSkully/rtttl-web-composer" alt="License Badge" /></a>
-	<a href="./package-lock.json" alt="package-lock"><img src="https://img.shields.io/badge/package--lock-committed-brightgreen" /></a>
-	<a href="https://skully.tech/discord" target="_blank" alt="Join Discord"><img src="https://img.shields.io/discord/820142202666876938.svg" /></a>
-	<a href="https://imskully.github.io/rtttl-web-composer" target="_blank"><img src="https://img.shields.io/static/v1?label=Demo&message=Preview&color=228be6" alt="Open Preview Badge" /></a>
+	<img alt="Discord Badge" src="https://img.shields.io/badge/on_discord-chat?style=flat&logo=discord&logoColor=%235865f2&label=chat&color=%235865f2&link=https%3A%2F%2Fdiscord.skully.tech" />
+	<a href="https://rtttl.skully.tech" target="_blank"><img src="https://img.shields.io/static/v1?label=Demo&message=Preview&color=228be6" alt="Open Web Application" /></a>
 </p>
 
-> [!NOTE]  
-> This README requires expansion.
+A rich web based composer for creating [Ring Tone Text Transfer Language (RTTTL)][1].
 
-A rich web based composer for creating [Ring Tone Text Transfer Language (RTTTL)](https://en.wikipedia.org/wiki/Ring_Tone_Text_Transfer_Language) ringtones:
+- 📝 Interactive, responsive, and user-friendly web interface for creating RTTTL ringtones
+- 🎶 Dynamic RTTTL generation and browser playback using [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
+- 📦 Generate or import RTTTL ringtone strings
 
-* 📝 Interactive, responsive, and user-friendly web interface for creating RTTTL ringtones
-* 🎶 Dynamic RTTTL generation and browser playback using [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
-* 📦 Generate or import RTTTL ringtone strings
-
-This web application is built with barebones HTML & CSS, and vanilla JavaScript for the sake of simplicity. The frontend uses the [Tabler UI](https://github.com/tabler/tabler) framework, [BS5](https://github.com/twbs/bootstrap), and [jQuery](https://jquery.com) for UI components and interactivity.
+This tool was originally built with vanilla HTML, CSS & JS for the sake of simplicity, but eventually outgrew the basics and required a web framework to streamline development and better comply with modern standards. The application is built using the [Fresh](https://fresh.deno.dev) web framework with [Deno](https://deno.com) for the backend and build process. The frontend also uses the [Tabler](https://github.com/tabler/tabler) UI framework, [BS5](https://github.com/twbs/bootstrap), and [jQuery](https://jquery.com) for interactivity.
 
 <div align="center" style="padding: 25px;">
-	<h3><a href="https://imskully.github.io/rtttl-web-composer" target="_blank" title="Open RTTTL Web Composer">Open Demo Application</a></h3>
+	<h3><a href="https://rtttl.skully.tech" target="_blank" title="Open RTTTL Web Composer">Open Demo Application</a></h3>
 	<img width="800" src=".github/readme_preview.png" alt="RTTTL Web Composer Logo" />
 </div>
 
-***
+---
 
 ## RTTTL
+> [!NOTE]\
+> For a more detailed description on RTTTL and its background history, specifications, and how it works, check out [*What is RTTTL?*](https://rtttl.skully.tech/rtttl_specification)
 
-Ring Tone Text Transfer Language (RTTTL) is a simple text-based format for ringtones originally developed by Nokia in the 1990s. In simple terms, an RTTTL string represents a melody and timing information - the format is relatively easy to understand, making it popular for creating ringtones on early mobile phones.
-
-In more modern usage, RTTTL is commonly found in Arduino/ESP8266/ESP32 projects that use a piezo buzzer for sound output.
-
-<details>
-	<summary><strong>RTTTL Format Specifications</strong></summary>
-
-	RTTTL (RingTone Text Transfer Language) is the primary format used to distribute 
-	ringtones for Nokia phones. An RTTTL file is a text file, containing the 
-	ringtone name, a control section and a section containing a comma separated 
-	sequence of ring tone commands. White space must be ignored by any reader 
-	application. 
+[RTTTL][1] *(Previously referred to as Nokring)* was originally developed in 1996 by Nokia for use in their mobile phones back when they were the dominant force in the mobile phone market and the most common method of composing, and sharing ringtones was through text messages. The format was simple and easy to understand which made its adoption quite popular though was quickly replaced by more modern formats such as [MIDI][2] and MP3 ringtones which offered more features and better sound quality.
 
-	Example: 
-	Simpsons:d=4,o=5,b=160:32p,c.6,e6,f#6,8a6,g.6,e6,c6,8a,8f#,8f#,8f#,2g
+The RTTTL format is still used today in some applications and devices such as hobbyist Arduino projects, IoT devices, and older mobile phones.
 
-	This file describes a ringtone whose name is 'Simpsons'. The control section 
-	sets the beats per minute at 160, the default note length as 4, and the default 
-	scale as Octave 5. 
-	<RTX file> := <name> ":" [<control section>] ":" <tone-commands>
+[1]: https://en.wikipedia.org/wiki/Ring_Tone_Text_Transfer_Language
+[2]: https://en.wikipedia.org/wiki/MIDI
 
-		<name> := <char> ; maximum name length 10 characters
+# Hardware
+If you are interested in playing ringtones composed in RTTTL on physical hardware, or you may already possess the necessary electrical components to build a simple circuit, you can use the following example below as a starting reference for the basics.
 
-		<control-section> := <control-pair> ["," <control-section>]
+Alternatively, if you prefer a ready-made hardware solution that comes ready to go out of the box then something like the [Apollo MSR-2](https://apolloautomation.com/products/msr-2) for Home Assistant is a great option for playing RTTTL. For more information on usage, refer to the [MSR-2 Buzzer](https://wiki.apolloautomation.com/products/msr2/examples/using-msr-2-buzzer/?h=rtt) documentation.
 
-			<control-pair> := <control-name> ["="] <control-value>
+## Components
+- **Microcontroller:** [ESP8266](https://amzn.to/4eaemqJ) / [ESP32](https://amzn.to/4eXCr5f), [Arduino Uno](https://amzn.to/4f6gAZw), or similar
+- **Audio:** [Piezo Buzzer](https://amzn.to/3C9JfOM) or similiar *(3-5V, must be passive)*, or I2S Speaker
+- **Wiring:** Jumper wires or breadboard
 
-			<control-name> := "o" | "d" | "b"
-			; Valid in control section: o=default scale, d=default duration, b=default beats per minute. 
-			; if not specified, defaults are 4=duration, 6=scale, 63=beats-per-minute
-			; any unknown control-names must be ignored
+## Circuit Diagram
+The following diagram is an example representation of a good basic circuit that connects a piezo buzzer to an ESP32 controller on a breadboard:
 
-			<tone-commands> := <tone-command> ["," <tone-commands>]
-
-			<tone-command> :=<note> | <control-pair>
-
-			<note> := [<duration>] <note> [<scale>] [<special-duration>] <delimiter>
-
-				<duration> := "1" | "2" | "4" | "8" | "16" | "32" 
-				; duration is divider of full note duration, eg. 4 represents a quarter note
-
-				<note> := "P" | "C" | "C#" | "D" | "D#" | "E" | "F" | "F#" | "G" | "G#" | "A" | "A#" | "B" 
-
-				<scale> :="4" | "5" | "6" | "7"
-				; Note that octave 4: A=440Hz, 5: A=880Hz, 6: A=1.76 kHz, 7: A=3.52 kHz
-				; The lowest note on the Nokia 61xx is A4, the highest is B7
-
-				<special-duration> := "." ; Dotted note
+<p align="center">
+	<img src="./.github/example_bradhboard_diagram.png" alt="ESP32 Buzzer Breadboard Diagram" width="450" />
+</p>
 
-	; End of specification
-</details>
+Note that the actual circuit will vary depending on your controller:
+- For ESP8266 boards, the software PWM output pins available are any in the range `GPIO0` - `GPIO16`
+- For ESP32 boards, the [LEDC PWM channel](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/ledc.html) can acts as output [*(diagram)*](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/_images/ledc-api-settings.jpg) and you can normally use any pin in the range `GPIO0` - `GPIO33`
+
+## Code
+If your microcontroller is compatible with ESPHome then you can fortunately make use of the existing RTTTL component to easily play the RTTTL strings composed on the web application directly on the ESP device, see the [RTTTL Component](https://esphome.io/components/buzzer.html#rtttl-component) documentation for more information, the source for the underlying RTTTL library can be found [here](https://esphome.io/api/rtttl_8h).
+
+```yaml
+# Buzzer (ESP32 controller)
+output:
+  - platform: ledc
+    pin: GPIO12
+    id: buzzer
+rtttl:
+    output: buzzer
+
+# Example API action
+api:
+  actions:
+    - action: play_rtttl
+      variables:
+        song_str: string
+      then:
+        - rtttl.play:
+            rtttl: !lambda 'return song_str;'
+```
+
+You can now invoke the `play_rtttl` action with `song_str` set to a valid RTTTL string such as:
+```yaml
+# Example RTTTL tone to play.
+song_str: "James Bond:d=4, o=5, b=320:c, 8d, 8d, d, 2d, c, c, c, c, 8d#, 8d#, 2d#, d, d, d, c, 8d, 8d, d, 2d, c, c, c, c, 8d#, 8d#, d#, 2d#, d, c#, c, c6, 1b., g, f, 1g."
+```
+
+# License
+This project is made available under the [GPL-2.0 License](./LICENSE).

components/Footer.tsx

@@ -0,0 +1,32 @@
+export function Footer() {
+	return (
+		<footer class="footer footer-transparent d-print-none">
+			<div class="container-xl">
+				<div class="row text-center align-items-center flex-row-reverse">
+					{/* Footer Links */}
+					<div class="col-lg-auto ms-lg-auto">
+						<ul class="list-inline list-inline-dots mb-0">
+							<li class="list-inline-item">
+								<a href="https://github.com/ImSkully/rtttl-web-composer" target="_blank" class="link-secondary">
+									View source on GitHub <i class="ti ti-external-link"></i>
+								</a>
+							</li>
+						</ul>
+					</div>
+
+					{/* Footer Text */}
+					<div class="col-12 col-lg-auto mt-3 mt-lg-0">
+						<ul class="list-inline list-inline-dots mb-0">
+							<li class="list-inline-item">
+								Made with ☕ by <a href="https://github.com/ImSkully" target="_blank" title="View GitHub Profile">Skully</a> &mdash;
+								<em>
+									Found this useful? <a href="https://www.buymeacoffee.com/Skully" target="_blank">Leave a tip</a>!
+								</em>
+							</li>
+						</ul>
+					</div>
+				</div>
+			</div>
+		</footer>
+	);
+}