Overtone is an audio environment for Clojure, based on SuperCollider. It's able not only to generate music, but also to process audio in real time. It's used for i.e. live-coding and collaborative jamming.
The main part of my proposal is porting Overtone, that is type checking it using core.typed, which is a great optional type system with stuff like dependent types built in and much easier than it is in i.e. Haskell. Porting Overtone is a great way to stress this type system and find its limits and test if it's able to express Overtone concepts. There is already a prelimitary attempt to type Overtone available here.
The second, much shorter, part is writing a tutorial. Overtone is pretty complicated, requires broad knowledge about music, programming and Clojure. It's also hard to install and not well documented. These are big obstacles to its adoption. Writing an introductory tutorial will significantly lower the entry barrier.
Annotating a library like Overtone should be carefully planned. The reason is simple -- Overtone is a huge library. It has 37.1k lines of code, measured using the following bash command:
wc -l $(git ls-files | grep '.*\.cs')
What's more, Overtone has dependencies that also need to be annotated. There are numerous dependencies, but thankfully all of them are small artifacts. Below I attach list of all dependencies along with size of their code base and a short description of their role.
1.1k org.clojure/data.json JSON parser/generator to/from Clojure data structures
1.4k clj-native JNA (Java Native Access)
0.4k overtone/at-at ahead of time function scheduler (`at`)
1.5k overtone/osc-clj support for Open Sound Control (a protocol for networking sound synthesizers)
0.3k overtone/byte-spec declarative DSL for reading and writing binary file formats
0.4k overtone/midi-clj a streamlined midi API for Clojure
0.6k overtone/libs.handlers event handlers library
na overtone/scsynth scsynth binaries for multiple operating systems and architectures
na overtone/scsynth-extras extra syscynth ugens
0.2k clj-glob glob patterns
5.0k org.clojure/core.match (only in Overtone.typed) optimized pattern matching library
Overtone is huge and annotating such big artifact without any plan is planning to fail. I need to do the following tasks.
-
Find a starting point, that is vars that you should start annotating from. These vars should depend on no or few other vars so annotating them all is easy.
-
Detect hard parts. One of the hard situation that may happen are circular vars, that is var A depends on B, B on C and C on A. In that case, all three vars need to be annotated atomically in one step to type check successfully. If there exists such cycle incorporating a lot of vars, it's hard to annotate.
-
Keep track where I am, what I'm going to do next and what to do when I get stuck.
My proposal to solve all these problems is preparing a vars graph. Each var in Overtone is represented as a node. If annotating A requires annotating B, then there is a dependency represented as a directed edge. If var A is defined in terms of var B, then annotating A requires annotating B and that introduces a new edge.
The full graph will be constructed automatically by a script that I will develop. To develop such script, I will reuse some code from existing source meta information extractors. You can find the list of such extractors along with their analysis in my proposal on another project called "source meta information model".
The next step is to linearize the graph by sorting it topologically. There will be probably many ways to linearize such graph so other factors will be taken into account:
- I'd like to first work at vars for which there exists some unit tests.
- I want to avoid situation when I annotated two huge, independent parts and then I merge them. Such integration is going to fail. I'll always prefer merging vars step-by-step.
After choosing starting point and linearizing the graph, I will start annotating var-by-var.
From time to time it will be necessary to change existing annotations. It's easy to get lost in such case so I will backtrack in my linearized graph to the first var that need to be changed, change it and go again var-by-var. That way I will always keep track where I am and I will never get lost.
It's possible that vars graph will have cycles. If such cycle is small I will just annotate all vars is the cycle atomically. If there exists huge cycle which cannot be solved in this way, special care must be taken. On the other hand, it's rather impossible for such big cycle to exists. Such big cycle would span across many namespaces and that would lead to import cycle.
The expected result of this task is linearized vars graph along with some alternative linearizations.
I'm going to spend at planning annotating about two weeks because this is very important task. The rest of time I will spend on just annotating and typing and on the second part of this proposal, that is writing a tutorial.
I'd like to notice that in general it's really hard to schedule such project because of two reasons. First reason is that this is mostly a research project and, by its nature, it's impossible to do any estimates and even to know if it will succeed. The second reason is that such estimates and plans requires already deep understanding of Overtone which I lack at this moment. However, I believe, that my approach with vars graph will help deliver at least a partial road map.
At the end of the summer I'd like to focus on writing tutorial for Overtone. After long period of annotating Overtone I will have a huge, deep understanding of Overtone internals. I think that it will be really beneficial if I share this knowledge and write a tutorial as a by-product.
Learning Overtone is really harsh at this moment. There are numerous reasons.
The first reason is that installation process is quite complicated. You need to install java, lein and SuperCollider. If you run Linux, you need JACK which is not trivial to configure (conflicts with PulseAudio, connecting inputs and outputs in "connections" window, installing and running with root, configuring operating system so JACK can run in real time). At the top of that, you need some IDE. My proposal is not about solving this problem.
The second reason is that learning Overtone requires broad knowledge and skills:
- music knowledge,
- programming knowledge,
- learning Clojure and its idioms; Clojure is much different from most mainstream languages and, therefore, you need to learn it a bit before using it;
- configuring and learning IDE; learning Emacs or vim is a big task; and even if you go the easiest and most sane way, that is IntelliJ + Cursive, you still need to get used to i.e. structural editing.
The last reason is that documentation is bad. I think that Django is a role model for documentation. It consists of three parts:
- step-by-step tutorial (aka introduction or quickstart) -- This is the first thing that someone sees when trying out a new library or environment. It should assume no previous knowledge of the library. All basic concepts should be introduced. Tutorial should show how the project "feels" and how to combine different pieces to make some useful project. It's also really important to make the first impression really good.
- topical guides (aka overviews) -- Once someone has learned the high-level concepts from a tutorial, it should be easy for the reader to understand such topical guides. They should show most common usage patterns.
- low-level, deep-dive reference manual -- Basically speaking the documentation of each artifact (function, macro and other vars). It can be stored in docstrings.
You can read more about ideas behind Django documentation at jacobian blog.
While some Overtone artifacts are documentated (so there is incomplete reference) and there are some topical guides on the github wiki, there is no tutorial.
Writing tutorial helps with the second and third obstacle to Overtone. The tutorial will be easy because I will not assume previous music or Clojure knowledge. I will assume only previous programming experience. What's more, I'm going to carefully analyze how many new concepts will be introduced in each tutorial chapter so each one will contains only few ones.
The goal of the tutorial will be to learn all the basic concepts of Overtone through small projects, so at the end the learner should be able to do its own projects using only reference and topical guides. I'd like to mention not only how to generate sound, but also how to process some input audio which is now completely uncovered.
I also believe that such tutorial should be "tested" by readers. I will encourage people to read the documentation while I will be writing it to make it perfect. I will start writing from the first chapter, so testing and writing will be easily parallelizable. I'm thinking about making some group of people who want to learn Overtone seriously to avoid situation when there are a lot of people reviewing first chapter and none for the third one.
I'd like to find out answers for the following questions:
- Why people want to learn Overtone?
- What features of Overtone are they interested in? I.e. is it music generation or processing input audio?
- Did they try to learn Overtone?
- What obstacles did they encounter?
- maybe through some Google Forms
to do some quantitative analysis and prioritize topics, to know which topics should I ignore in tutorial and what topics most people expect to be mentioned in the tutorial.
The next one is to find a lot of example small projects well suited to teach new Overtone concepts, metaphores used to learn music concepts, ways to learn Overtone (what to do first, what later), things and topics that are tough or avoided. I will search for these stuff in:
- youtube movies about Overtone,
- examples in Overtone source code,
- existing documentation.
I will also produce a list of all topics and concepts along with their dependencies in the form of graph. This graph will be then sorted topologically to ensure that I don't assume knowledge of a concept that is introduced in later chapter. There is also another reason: such formal way makes it much easier to track how many new concepts are introduced in each chapter. That easies ensuring that each chapter introduces only few new concepts. The result of this step is a list of chapters. For each chapter I will enumerate:
- new concepts that will be introduced in this chapter,
- useful project(s) (if any) that will be realized in this chapter,
- examples that will be presented in this chapter.
I will also provide detailed timeline for the next task.
I will start from the first chapter. As I mentioned previously, I will also encourage community to give me feedback.
I've an idea of using data how people read documentation to make interesting conclusions. For example, we could track not only the page that readers are reading, but also the exact place where they are (by reading vertical slider position). Analyzing such data could show us for example where do people get stuck, at which moment they give up and close docs and so on. Unfortunately, I don't know of any documentation hosts providing such features. And since the scope of this project is entirely different, I couldn't write such stuff. But if anybody knows some way to incorporate some measurements to make documentation better, please contact me.
If time allows, I will also improve docstrings, especially for these artifacts which I will mention in the tutorial. I don't consider this step a priority since it's not impossible to use some library with excellent tutorial and uncompleted reference, but it doesn't work the other way.
-
Community bounding period
- learning core.typed
- understanding the existing prototype for Typed Overtone
- learning Overtone
-
1st & 2nd week
- planning typing
- updating existing Typed Overtone propotype to the newest Overtone (existing prototype was forked one year ago and Overtone has changed since that time)
- delivering detailed plan for 3rd & 4th week
-
3rd & 4th week
- annotating & typing
-
5th week
- I'd like to schedule one week to prepare to exams on university.
-
6th week
- preparing detailed road map for weeks 7, 8, 9 and 10; the estimation for weeks 3rd & 4th and the real achievements will be compared to make estimation for the next 4 weeks more precise and avoid under- and over-estimation; the road map will be delivered before mid term evaluation;
- annotating & typing
Friday of 6th week -- mid term evaluation
-
7th -- 9th week
- annotating & typing
-
10th week
- annotating & typing
- sharing knowledge and experience how to deal with annotating large code base and what I've learned
-
11th week
-
12th week
-
13th week
Friday of 13th week: suggested "pencils down" date
-
14th week
- buffer week
Friday of 14th week: firm "pencils down" date*
The benefits of typed Overtone is not typed Overtone but actually stressing core.typed and finding its limitations.
After the summer I will have experience with annotating huge project like Overtone. The reality will test if my approach with dependency graph works, how to deal with cycles and so on. I will share this knowledge.
I believe that this will attract people to core.typed because it will be a proof that it can be used in projects with large code base. What's more, I will share my knowledge so it will be made public how to switch to typed code easily, what traps need to be avoided and so on. This will significantly lower risk and, therefore, make using core.typed more attractive. My script to make vars graph could be reused.
I believe that, to became popular, it's not enough for a programming language to just be better than other ones. I thing that a language need to find a niche or have some killer app/library/framework. Python became popular thanks to Django web framework which made it much easier to rapidly write web applications. At the same time, it's common among scientists because it has really good support for scientific computing (think of numpy or scipy). The same is true for i.e. Ruby & Rails.
I think that Overtone can be such killer app. There is no easy way for generating or processing music now. Clojure community can gain a lot by making it a killer app and de facto standard audio environment. But we need to foster it's adoption by making the barrier as low as possible. Writing an excellent tutorial is the first thing to do.
I'd also like to notice that while the first part (Typed Overtone) is risky and may fail, the last one is something that will be done for sure. So even if I will fail with typing, Clojure community will benefit from great tutorial.
My name is Christopher Mędrela and I'm a student of University of Science and
Technology in Kraków (Poland). My time zone is UTC+01:00. My email address is
chris.medrela+gsoc2015 at gmail.com. I have a github account.
My main language is Python, but sometimes I fed up and I want something less mutable, easier to reason about, with functions instead of classes, and generally speaking more functional. I'm excited about Clojure since it fits my needs and it integrates with Java so "batteries are included". I heard about Clojure because I often look at other languages to remain fresh in mind. My Clojure is not fluent yet, but I think I'm familiar enough with Clojure to manage this project. I've written one bigger project at my university in ClojureScript using ReactJS (Om, actually).
I'm contributor of open source projects since 2011. I worked mainly at Django. I've written a lot of patches.
This is the third time I apply to Google Summer of Code. My first SoC was revamping Django check framework (see proposal and merge commit). I've learnt how to deal with large code base. Last year I worked on Breeze (Scala numerical library) (see my commits at the master branch). I've learnt functinoal programming and Java/Scala ecosystem. I finished both projects successfully. I used git extensively during both projects.
I'm active in local user groups in Cracow. For example, I regularly attempt pykonik, Python group in Cracow. I was also a volunteer on Lambda Days.
My English is not fluent but I can talk in real time via i.e. skype.
I have exams at my university starting at June 23 and ending at July 5. I'd like to reverse one week to prepare for exams, which is reflected in the schedule. I don't have any time consuming activities after July 5. I'm not applying as a student to any other GSoC organization. I'm applying for another project called "Source meta information model proposal", but I'd like to work at "core.typed Porting Experiment: Overtone" project.