breval/blip
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs.rs index

Browse source
This commit is contained in:
brevalferrari 2025-06-07 18:18:40 +02:00
parent 45d384cb85
commit 2f5d9aed32
2 changed files with 112 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

108
src/DOCS.md Normal file
View file

@ -0,0 +1,108 @@
# bliplib <!-- omit from toc -->
This is the core library for the Bizarre Language for Intermodulation Programming (BLIP).
This crate also contains the binary `blip`.
BLIP is a music scripting language made by nerds for nerds.
It uses math and physics in a modular grammar to generate sound your way.
- [Design](#design)
- [History](#history)
- [Features](#features)
- [Your notes](#your-notes)
- [Your variables](#your-variables)
- [Your own instrument](#your-own-instrument)
- [Time is yours](#time-is-yours)
- [Defaults](#defaults)
- [Expressions](#expressions)
- [Grammar](#grammar)
- [Two wolves](#two-wolves)
- [Binary](#binary)
- [Lib](#lib)
- [Thanks](#thanks)
## Design
### History
Computer assisted music production started from the 50's to the 70's and got popular when computers became cheaper and more powerful. A lot of new tools gave us new ways of making music. As any tool, they also shaped the art we made with it in many ways. For example, most Digital Audio Workstations (DAWs) use "patterns" and allow to easily compose a song with drag-and-drop loops. This made our music easily more repetitive and contributed to completely new genres. A lot of electronic dance genres would probably not exist without this technique which was inspired by common artistic repetition techniques used across all modern history.
Today, the diversity and availability of these tools seems more than ever linked to the diversity of our art styles because we can achieve so much more with a computer that we rely a lot on these tools. So by contributing to the world of computer assisted music production tools, we directly contribute to our artistic diversity.
My first steps into this rabbit hole started when I found [BeepComp](http://hiromorozumi.com/beepcomp/), an editor for a custom [MML](https://en.wikipedia.org/wiki/Music_Macro_Language) variant. I became fascinated by the software but even more by this new way of thinking about music. Languages all have their own logic and constraints. [MIDI](https://en.wikipedia.org/wiki/MIDI) for example comes with a language that is very precise but almost impossible to write by hand (it's made of bytes) and the standard implies a specific bank of pre-generated sounds and natively only works with a standard set of 12 notes.
### Features
The main idea behind this language is to free constraints imposed by other similar languages, starting with the note set.
#### Your notes
As such, you specify how many notes fit in your set and what their names are.
Now, if you're familiar with music, you may have noticed I say "set" and not "octave". This is also intentional : you decide if you want octaves or not, and how they act on the frequencies of your notes or on the generated sound globally.
#### Your variables
If you want octaves, you can make a variable store the value of the current octave. You can define any variable and use them to change any parametter of your current song.
#### Your own instrument
There is no imposed sound bank for you to choose from. You make your own. On computers, audio is just a bunch of points with amplitudes, so you give the program a mathematical expression. Everytime you want sound to be generated, your expression will be evaluated with the current variables.
> Don't worry, the binary includes default expressions for everything. You can override them whenever you want to.
#### Time is yours
Standard [MML](https://en.wikipedia.org/wiki/Music_Macro_Language) variations impose a value for a length but they don't all agree (4 means a quarter note? or is it 4 seconds? what about the tempo?). BLIP doesn't know how much time any of your notes last. You give another mathematical expression that outputs a number of seconds for a note to last using the current values of your variables.
#### Defaults
The BLIP library needs one default variable for the elapsed time in seconds, another one for the note index of the current note played in your set of notes and a last one for the length of notes in seconds, filled by the length expression. The binary program uses `'t'` for time, `'n'` for the current note index and `'L'` for note lengths in seconds.
It also includes :
- `sin(2*pi()*(442*2^((n+1)/N))*t)` for the default instrument
- `2^(2-log(2, l))*(60/T)` for the default length expression
As well as some variables :
| var | value | meaning |
| --- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| l | 4 | length of the notes ([BeepComp style](http://www.hiromorozumi.com/beepcomp/documentation/beepcomp_users_guide.html#music_section_note_length)) |
| L | 0 | length of the notes in seconds (filled by the length expression) |
| t | 0 | elapsed time in seconds |
| T | 60 | tempo (beats per minute / BPM) used in the length expression |
| N | number of notes in the set | used to divide the frequencies for all the notes in the octave (instrument expression) |
#### Expressions
BLIP uses [`fasteval`](https://crates.io/crates/fasteval). Check out its [syntax](https://docs.rs/fasteval/latest/fasteval/#the-fasteval-expression-mini-language) to know what you can put in your expression. This is also available in the `memo` menu of the program.
### Grammar
For the language grammar, see [doc/cli-design.txt](../doc/language-design.txt) or the the `memo` menu of the program.
## Two wolves
([meme](https://i.kym-cdn.com/entries/icons/original/000/029/963/inside_you_there_are_two_wolves.png))
### Binary
You can use `cargo install` to install the binary. You will need the `bin` feature.
```sh
cargo install bliplib --features bin
```
Then, follow `blip --help` for instructions on how to use the program.
### Lib
The library is designed to ease the integration of this language into various tools like GUIs and editor extensions.
You can (hopefully) add tokens to the language given you specify how to parse and compile it by either creating wrappers for [`parser::Parser`] and [`compiler::Context`] in your own crate or edit this crate by cloning [the GitDab repo](https://gitdab.com/breval/blip) (or forking if you can).
Everything here is subject to an MIT license which allows you to do almost everything you want with this code as long as you include my [notice](../LICENSE).
## Thanks
This project was made for a Bachelor's Degree in Computer Science at the UQAC (Québec University at Chicoutimi / Université du Québec à Chicoutimi) and many thanks goes to Abdenour Bouzouane for his advice and for allowing me to reuse my ideas for my degree.
This project takes its roots into the first implementations of the [Music Macro Language](https://en.wikipedia.org/wiki/Music_Macro_Language) and would not exist without this great idea. Thank you to all contributors of this niche world of composition tools, especially contributors of [Pure Data](https://github.com/pure-data/pure-data), [SuperCollider](https://supercollider.github.io/) and [Sonic Pi](https://sonic-pi.net/). Special thanks goes to the very kind [Hiro Morozumi](http://hiromorozumi.com/) for the love he put in [BeepComp](http://hiromorozumi.com/beepcomp/). I wish you all the best.

4
src/lib.rs
View file

@ -1,2 +1,6 @@
#![doc = include_str!("DOCS.md")]
/// Compilation stuff (for turning tokens into samples)
pub mod compiler;
/// Parsing stuff (for turning strings into tokens)
pub mod parser;