JSynth Documentation

This is a documentation for JSynth, an online "synthesizer" I'm currently working on. It explains how the JSON-based format works, and it includes a changelog at the very end.

Format

JSynth's format is based on JSON, which you can read on here. However, reading its documentation is not required to understand JSynth, although it is recommended.

The basic concept goes as follows. JSynth stores melodies in terms of successive chords. Each chord contains various channels, and these channels are of two types: Notes or holding channels. Notes cancel the current sound being played through the channel and may or not play a new one (acting also as rests), holding channels instead leave it unchanged. Extra properties that modify any element of the song may then be set.

Every JSynth file begins and ends with { and } braces. As follows are the values to be filled inside them, in alphabetical and then hierarchical order:

It is recommended to read about the non-optional values first.

Each value is filled as value: x. This x may be either a string, enclosed in "quotation marks", or a true/false. value (written as is). Using the incorrect type of object or other types of objects, such as numbers not surrounded by quotation marks, may result in unplanned behavior. Objects, with various values, are enclosed in braces, such as {value1: x, value2: y}. Arrays, which are ordered collections of objects, are enclosed in brackets, such as [value1: x, value2: y}. One can then write the file accordingly, filling each field as required.

Properties

bpm

Represents the BPM of the song on which relative duration is based, as a number. Required only when relative duration is used.

channels

In JSynth, each chord is made out of channels. Channels either play a new note, or sustain a previous one, and the number of channels a chord can contain are unlimited, allowing for equally unlimited polyphony. The channels are stored as an array.

default_vol

If the vol of a note isn't specified, JSynth will fall back to default_vol, stored in the same format. Then, if this value is not specified, JSynth will throw an error.

default_wave

If the wave of a note isn't specified, JSynth will fall back to default_wave, stored in the same format. Then, if this value is not specified, JSynth will throw an error.

duration

The duration of a chord can be specified, just as the freq in one of two ways: As an absolute measurement in terms of either seconds s, milliseconds ms or minutes m/min, or as a relative measurement, in terms of the bpm (if specified). Strings such as "1s" or "0.5 m" are automatically interpreted as absolute, while strings such as "1", "50.5" or even "1/3.5" are interpreted as fractions of one beat. Note that absolute measurements can't be typed as fractions.

It is worthy of mention that although the duration controls the entire chord, notes with different lengths may still be played simultaneously, by use of holding channels.

freq

The frequency of a note can be specified, just as the duration in one of two ways: As an absolute measurement in terms of hertz hz, or as a relative measurement, in terms of either cents c/cents, millioctaves mo or octaves o relative to the root (if specified), or as tones in an EDO as x\y (meaning 2x⁄y times the root). Strings such as "1hz" or "0.5m" are automatically interpreted as absolute or relative depending on the unit of use.

held

Specifies whether a channel will simply leech off the previous one. false by default.

notes

The core of the format, containing an array of chords in temporal order (and therefore storing all of the song's notes, hence the name).

root

Specifies the root of the song in Hz as a single number.

wave

Specifies the waveform of a note. Does nothing on held channels. The options are as follows:

  • "sn", "sin", "sine", "sinewave": Sine wave.
  • "tr", "tri", "triangle": Triangle wave.
  • "sq", "sqr", "square": Square wave.
  • "sw", "saw", "sawtooth": Sawtooth wave.

vol

Specifies the volume of a note as a number between 0 and 1 representing the amplitude of the channel. This number may be a percentage, as in "50%". It may alternatively represent the volume in terms of decibels as "-3db". This value is default_vol by default.

Changelog

1.0.1 (May 2, 2018)

Frequency can now be specified in the form x\y, being interpreted as x tones above the root in y-EDO.

1.0.2 (July 20, 2018)

Fixed a bug that disallowed saving files over 16 seconds in length in Chrome.

Fixed a bug that disabled absolute time functionality.

Added default_wave and wave.

Comments

Post a Comment

Popular posts from this blog

Tuning is impossible – an interactive.

Image
Table of Contents Motivation Prerequisites Basics of sound Harmony How we came up with the number twelve Alternatives and solutions Conclusion Addendum References Motivation I want to talk about something I've had in my head for a while now, and that partially inspired me to create this blog. Something embedded in every melody, but complex in its own right and something I had implicitly taken for granted my entire life: Tuning systems. But before I can start my monologue on the topic, we'll need to get some things clear, specifically, how sounds work, and why some sounds are more harmonious than others. This will get somewhat long, since I'll be trying to be as clear as possible, but bear with me and you'll start hearing music in a completely different manner. Prerequisites Basic music theory kn
Read more

I made a song

Image
I made this Techno song quite a while ago. I released it as part of a new label between some members of a group I'm in. Objectively not the best, but I'll be bringing much better soon. Here's a download link: https://mega.nz/#!3o02WTSR!gAWfsgyd81qPFYEWYXyZYdhQ6fItV_75wXQ3NXjTJ3g
Read more