musicpy
=======
[English [中文](#musicpy-1)]
Have you ever thought about writing music with codes in a very concise, human-readable syntax?
Musicpy is a music programming language in Python designed to write music in very handy syntax through music theory and algorithms. It is easy to learn and write, easy to read, and incorporates a fully computerized music theory system.
Musicpy can do way more than just writing music. This package can also be used to analyze music through music theory logic, and you can design algorithms to explore the endless possibilities of music, all with musicpy.
With musicpy, you can express notes, chords, melodies, rhythms, volumes and other information of a piece of music with a very concise syntax. It can generate music through music theory logic and perform advanced music theory operations. You can easily output musicpy codes into MIDI file format, and you can also easily load any MIDI files and convert to musicpy's data structures to do a lot of advanced music theory operations. The syntax of musicpy is very concise and flexible, and it makes the codes written in musicpy very human-readable, and musicpy is fully compatible with python, which means you can write python codes to interact with musicpy. Because musicpy is involved with everything in music theory, I recommend using this package after learning at least some fundamentals of music theory so you can use musicpy more clearly and satisfiedly. On the other hand, you should be able to play around with them after having a look at this [wiki](https://github.com/Rainbow-Dreamer/musicpy/wiki) I wrote if you are already familiar with music theory.
Documentation
-------------
See [musicpy wiki](https://github.com/Rainbow-Dreamer/musicpy/wiki) for complete and detailed tutorials about syntax, data structures and usages of musicpy.
This wiki is updated frequently, since new functions and abilities are adding to musicpy regularly.
The syntax and abilities of this wiki is synchronized with the latest released version of musicpy.
[Musicpy introduction and tutorial video part 1](https://www.bilibili.com/video/BV1754y197a9/)
[Musicpy composition examples demonstration and musicpy experimental compositions video](https://www.bilibili.com/video/BV18z4y1r7Pk/)
Musicpy's data structures, basic syntax, usage and more details are in this [wiki](https://github.com/Rainbow-Dreamer/musicpy/wiki), I'll try to make sure everything is detailed and clear, and with examples.
You can click [here](https://www.jianguoyun.com/p/DRJrawoQhPG0CBiL2fMD) to download the entire wiki of musicpy I written in pdf and markdown format, which is updating continuously.
Installation
-------------
Make sure you have installed python (version >= 3.7) in your pc first.
Run the following line in the terminal to install musicpy by pip.
```shell
pip install musicpy
```
In addition, I also wrote a musicpy editor for writing and compiling musicpy code more easily than regular python IDE with real-time automatic compilation and execution, there are some syntactic sugar and you can listen to the music generating from your musicpy code on the fly, it is more convenient and interactive.
I strongly recommend to use this musicpy editor to write musicpy code.
You can download this musicpy editor at the repository [musicpy_editor](https://github.com/Rainbow-Dreamer/musicpy_editor), the preparation steps are in the README.
Musicpy is all compatible with Windows, macOS and Linux, but there are some important notes if you encounter some errors on Linux or macOS.
Note1: If you encounter ```pygame.error: Couldn't open /etc/timidity/freepats.cfg``` errors on Linux, here is the solutions to fix it, open the terminal and run `sudo apt-get install freepats` and it will fix the errors.
Note2: If you are using macOS, and you encounter problems when you run musicpy codes using your current python version, please use python 3.7.1/3.7.9 to run musicpy, because it seems that on macOS, some of the requirements python modules of musicpy may not be compatible with some of the newer python versions. It is tested by my friend that on macOS with python 3.7.1 (and python 3.7.9 tested by me), musicpy could run and play the musicpy codes without any errors, but other versions may not. If you don't have problems when you run musicpy codes using your current python version, then you don't need to refer to this note.
Note3: On all of Windows, macOS and Linux, you can use pip to install musicpy in cmd/terminal.
Note 4: Some python IDEs may prevent the function to play music of musicpy, which makes the music cannot be played normally when playing the codes, such as VS Code, PyCharm, here it is recommended to use more interactive python IDE, such as Jupyter Notebook, Wing IDE, or directly use the interactive shell of python in cmd/terminal (run `python` to enter).
Importing
-------------
Place this line at the start of the files you want to have it used in.
```python
from musicpy import *
```
or
```python
import musicpy as mp
```
to avoid possible conflicts with the function names and variable names of other modules.
Composition Examples
-------------
Because musicpy has too many features to introduce, I will just give a simple example code of music programming in musicpy:
```python
# a nylon string guitar plays broken chords on a chord progression
guitar = (C('CM7', 3, 1/4, 1/8)^2 |
C('G7sus', 2, 1/4, 1/8)^2 |
C('A7sus', 2, 1/4, 1/8)^2 |
C('Em7', 2, 1/4, 1/8)^2 |
C('FM7', 2, 1/4, 1/8)^2 |
C('CM7', 3, 1/4, 1/8)@1 |
C('AbM7', 2, 1/4, 1/8)^2 |
C('G7sus', 2, 1/4, 1/8)^2) * 2
play(guitar, bpm=100, instrument=25)
```
[Click here to hear what this sounds like (Microsoft GS Wavetable Synth)](https://drive.google.com/file/d/104QnivVmBH395dLaUKnvEXSC5ZBDBt2E/view?usp=sharing)
If you think this is too simple, musicpy could also produce music like [this](https://drive.google.com/file/d/1j66Ux0KYMiOW6yHGBidIhwF9zcbDG5W0/view?usp=sharing) within 30 lines of code (could be even shorter if you don't care about readability). Anyway, this is just an example of a very short piece of electronic dance music, and not for complexity.
For more musicpy composition examples, please refer to the musicpy composition examples chapters in wiki.
Brief Introduction of Data Structures
-------------
`note`, `chord`, `scale` are the basic classes in musicpy that builds up the base of music programming, and there are way more musical classes in musicpy.
Because of musicpy's data structure design, the `note` class is congruent to integers, which means that it can be used as int directly.
The `chord` class is the set of notes, which means that it itself can be seen as a set of integers, a vector, or even a matrix (e.g. a set of chord progressions can be seen as a combination of multiple vectors, which results in a form of matrix with lines and columns indexed)
Because of that, `note`, `chord` and `scale` classes can all be arithmetically used in calculation, with examples of Linear Algebra and Discrete Mathmetics. It is also possible to write an algorithm following music theory logics using musicpy's data structure, or to perform experiments on music with the help of pure mathematics logics.
Many experimental music styles nowadays, like serialism, aleatoric music, postmodern music (like minimalist music), are theoretically possible to make upon the arithmetically performable data structures provided in musicpy. Of course musicpy can be used to write any kind of classical music, jazz, or pop music.
For more detailed descriptions of data structures of musicpy, please refer to wiki.
Summary
-------------
I started to develop musicpy in October 2019, currently musicpy has a complete set of music theory logic syntax, and there are many composing and arranging functions as well as ad
评论0