Merge pull request #123 from tidalcycles/0.8-dev

0.8 release

HACKING.md

@@ -1,8 +1,22 @@
-In-progress..
+# Community
+
+The below might help, but to find people to ask questions about
+getting started, join the tidal-innards channel on the TOPLAP slack:
+  http://toplap.org/toplap-on-slack/
+
+You can also ask on the mailing list:
+  http://lurk.org/groups/tidal/
 
 # Quick guide to contributing a change to Tidal
 
-How to..
+The main repository is maintained on github:
+  https://github.com/tidalcycles/tidalcycles.github.io
+
+The SuperDirt repository is here:
+  https://github.com/musikinformatik/SuperDirt
+
+We'd like to add some instructions for how to interact with these but
+no one has done it yet. For now some bullet points as a placeholder:
 
 * Make a dev fork
 * Make and test a change
@@ -11,7 +25,7 @@ How to..
 
 # A process for making a release
 
-How to..
+Likewise, we'd like to describe how to..
 
 * Share with others for testing
 * Tagging release

Sound/Tidal/Compositions.hs

@@ -0,0 +1,21 @@
+{-|
+Module: Compositions
+Description: compose multiple pattern into more complex patterns
+
+Some functions work with multiple sets of patterns, interlace them or play them successively.
+-}
+module Sound.Tidal.Compositions (append,
+                                 append',
+                                 cat,
+                                 randcat,
+                                 seqP,
+                                 slowcat,
+                                 stack,
+                                 superimpose,
+                                 wedge,
+                                 interlace,
+                                 spin,
+                                 weave) where
+
+import Sound.Tidal.Pattern
+import Sound.Tidal.Strategies

Sound/Tidal/ConditionalTransformers.hs

@@ -0,0 +1,11 @@
+{-|
+Module: ConditionalTransformers
+Description: conditionally apply other transformations to pattern
+
+Conditional transformers are functions that apply other transformations under certain cirumstances. These can be based upon the number of cycles, probability or time-range within a pattern.-}
+module Sound.Tidal.ConditionalTransformers (every,
+                                            foldEvery,
+                                            sometimesBy,
+                                            whenmod,
+                                            within) where
+import Sound.Tidal.Pattern

Sound/Tidal/Context.hs

@@ -15,7 +15,3 @@ import Sound.Tidal.Time as C
 import Sound.Tidal.SuperCollider as C
 import Sound.Tidal.Params as C
 import Sound.Tidal.Transition as C
-import Sound.Tidal.MidiStream as C
-import Sound.Tidal.MIDI.Params as C
-import Sound.Tidal.Synth as C
-import Sound.Tidal.SerialStream as C

Sound/Tidal/Dirt.hs

@@ -52,7 +52,10 @@ dirt = Shape {   params = [ s_p,
                             bandq_p,
                             unit_p,
                             loop_p,
-                            n_p
+                            n_p,
+                            attack_p,
+                            hold_p,
+                            release_p
                           ],
                  cpsStamp = True,
                  latency = 0.04
@@ -69,15 +72,15 @@ superDirtSlang = dirtSlang { timestamp = BundleStamp, path = "/play2", namedPara
 
 superDirtBackend port = do
   s <- makeConnection "127.0.0.1" port superDirtSlang
-  return $ Backend s
+  return $ Backend s (\_ _ _ -> return ())
 
 superDirtState port = do
   backend <- superDirtBackend port
   Sound.Tidal.Stream.state backend dirt
 
 dirtBackend = do
   s <- makeConnection "127.0.0.1" 7771 dirtSlang
-  return $ Backend s
+  return $ Backend s (\_ _ _ -> return ())
 
 -- dirtstart name = start "127.0.0.1" 7771 dirt
 
@@ -146,21 +149,69 @@ visualcallback = do t <- ticker
 pick :: String -> Int -> String
 pick name n = name ++ ":" ++ (show n)
 
+{- | Striate is a kind of granulator, for example:
+
+@
+d1 $ striate 3 $ sound "ho ho:2 ho:3 hc"
+@
+
+This plays the loop the given number of times, but triggering
+progressive portions of each sample. So in this case it plays the loop
+three times, the first time playing the first third of each sample,
+then the second time playing the second third of each sample, etc..
+With the highhat samples in the above example it sounds a bit like
+reverb, but it isn't really.
+
+You can also use striate with very long samples, to cut it into short
+chunks and pattern those chunks. This is where things get towards
+granular synthesis. The following cuts a sample into 128 parts, plays
+it over 8 cycles and manipulates those parts by reversing and rotating
+the loops.
+
+@
+d1 $  slow 8 $ striate 128 $ sound "bev"
+@
+-}
 striate :: Int -> ParamPattern -> ParamPattern
 striate n p = cat $ map (\x -> off (fromIntegral x) p) [0 .. n-1]
   where off i p = p
                   # begin (atom (fromIntegral i / fromIntegral n))
                   # end (atom (fromIntegral (i+1) / fromIntegral n))
 
+{-|
+The `striate'` function is a variant of `striate` with an extra
+parameter, which specifies the length of each part. The `striate'`
+function still scans across the sample over a single cycle, but if
+each bit is longer, it creates a sort of stuttering effect. For
+example the following will cut the bev sample into 32 parts, but each
+will be 1/16th of a sample long:
+
+@
+d1 $ slow 32 $ striate' 32 (1/16) $ sound "bev"
+@
+
+Note that `striate` uses the `begin` and `end` parameters
+internally. This means that if you're using `striate` (or `striate'`)
+you probably shouldn't also specify `begin` or `end`. -}
 striate' :: Int -> Double -> ParamPattern -> ParamPattern
 striate' n f p = cat $ map (\x -> off (fromIntegral x) p) [0 .. n-1]
   where off i p = p # begin (atom (slot * i) :: Pattern Double) # end (atom ((slot * i) + f) :: Pattern Double)
         slot = (1 - f) / (fromIntegral n)
 
+{- | _not sure what this does_, variant of `striate` -}
 striateO :: ParamPattern -> Int -> Double -> ParamPattern
 striateO p n o = cat $ map (\x -> off (fromIntegral x) p) [0 .. n-1]
   where off i p = p # begin ((atom $ (fromIntegral i / fromIntegral n) + o) :: Pattern Double) # end ((atom $ (fromIntegral (i+1) / fromIntegral n) + o) :: Pattern Double)
 
+{- | Just like `striate`, but also loops each sample chunk a number of times specified in the second argument.
+The primed version is just like `striate'`, where the loop count is the third argument. For example:
+
+@
+d1 $ striateL' 3 0.125 4 $ sound "feel sn:2"
+@
+
+Like `striate`, these use the `begin` and `end` parameters internally, as well as the `loop` parameter for these versions.
+-}
 striateL :: Int -> Int -> ParamPattern -> ParamPattern
 striateL n l p = striate n p # loop (atom $ fromIntegral l)
 striateL' n f l p = striate' n f p # loop (atom $ fromIntegral l)
@@ -175,26 +226,74 @@ clutchIn t now (p:p':_) = overlay (fadeOut' now t p') (fadeIn' now t p)
 clutch :: Time -> [Pattern a] -> Pattern a
 clutch = clutchIn 2
 
+{- | crossfades between old and new pattern over given number of cycles, e.g.:
+
+@
+d1 $ sound "bd sn"
+
+t1 (xfadeIn 16) $ sound "jvbass*3"
+@
+
+Will fade over 16 cycles from "bd sn" to "jvbass*3"
+-}
 xfadeIn :: Time -> Time -> [ParamPattern] -> ParamPattern
 xfadeIn _ _ [] = silence
 xfadeIn _ _ (p:[]) = p
 xfadeIn t now (p:p':_) = overlay (p |*| gain (now ~> (slow t envEqR))) (p' |*| gain (now ~> (slow t (envEq))))
 
+{- | 
+Crossfade between old and new pattern over the next two cycles.
+
+@
+d1 $ sound "bd sn"
+
+t1 xfade $ sound "can*3"
+@
+
+`xfade` is built with `xfadeIn` in this case taking two cycles for the fade.
+-}
 xfade :: Time -> [ParamPattern] -> ParamPattern
 xfade = xfadeIn 2
 
+{- | Stut applies a type of delay to a pattern. It has three parameters, 
+which could be called depth, feedback and time. Depth is an integer
+and the others floating point. This adds a bit of echo:
+
+@
+d1 $ stut 4 0.5 0.2 $ sound "bd sn"
+@
+
+The above results in 4 echos, each one 50% quieter than the last, 
+with 1/5th of a cycle between them. It is possible to reverse the echo:
+
+@
+d1 $ stut 4 0.5 (-0.2) $ sound "bd sn"
+@
+-}
 stut :: Integer -> Double -> Rational -> ParamPattern -> ParamPattern
 stut steps feedback time p = stack (p:(map (\x -> (((x%steps)*time) ~> (p |*| gain (pure $ scale (fromIntegral x))))) [1..(steps-1)]))
   where scale x
           = ((+feedback) . (*(1-feedback)) . (/(fromIntegral steps)) . ((fromIntegral steps)-)) x
 
+{- | _not sure what this does_, variant of `stut`
+-}
 stut' :: Integer -> Time -> (ParamPattern -> ParamPattern) -> ParamPattern -> ParamPattern
 stut' steps steptime f p | steps <= 0 = p
                          | otherwise = overlay (f (steptime ~> stut' (steps-1) steptime f p)) p
 
--- Increase comb filter to anticipate 'drop' to next pattern
+{-| same as `anticipate` though it allows you to specify the number of cycles until dropping to the new pattern, e.g.:
+
+@
+d1 $ sound "jvbass(3,8)"
+
+t1 (anticipateIn 4) $ sound "jvbass(5,8)"
+@-}
 anticipateIn :: Time -> Time -> [ParamPattern] -> ParamPattern
 anticipateIn t now = wash (spread' (stut 8 0.2) (now ~> (slow t $ (toRational . (1-)) <$> envL))) t now
 
+{- | `anticipate` is an increasing comb filter.
+
+Build up some tension, culminating in a _drop_ to the new pattern after 8 cycles.
+-}
 anticipate :: Time -> [ParamPattern] -> ParamPattern
 anticipate = anticipateIn 8