feat: add new Ableton file type documentation and overview

codekiln · codekiln · commit 8c0f628a8018 · 2025-09-10T05:28:41.000-04:00
- Created new markdown files for various Ableton file types, including `.adg`, `.adv`, `.agr`, `.alc`, `.alp`, `.als`, `.ams`, `.amxd`, `.asd`, and `.ask`, detailing their purposes, formats, and Git storage recommendations.
- Added a comprehensive overview page for Ableton file types, explaining their significance in version control and providing guidelines for handling different formats.
- Enhanced existing documentation with links to related resources and best practices for using Git with Ableton files.
diff --git a/journals/2025_09_10.md b/journals/2025_09_10.md
@@ -0,0 +1,3 @@
+## Audio
+	- [[Ableton/File]]
+	- [[Ableton/File/Concept/Storing in Git]]
diff --git a/pages/Ableton___File.md b/pages/Ableton___File.md
@@ -0,0 +1,40 @@
+alias:: [[Ableton/File Types]], [[Ableton File Types]], [[Ableton/File/Concept/Storing in Git]] 
+tags:: [[Diataxis/Explanation]]
+
+- # Ableton File Types – Conceptual Overview
+	- ## Overview
+		- Ableton Live uses a variety of proprietary file types to represent sets, clips, presets, and metadata. Some are human-readable (XML or JSON), others are binary. Understanding these formats is essential for workflows involving version control (e.g., Git).
+	- ## Context
+		- Many Ableton users want to store projects in Git for collaboration, history, and diffs. The challenge is that some file types are opaque binaries, while others can be normalized for text-based diffs. Knowing which is which helps decide what to commit, ignore, or preprocess.
+	- ## Key Principles
+		- **Textual formats** (XML/JSON) are git-friendly with proper filters.
+		- **Binary formats** (analysis files, waveforms, grooves) are not useful to version and can be regenerated.
+		- **Archive formats** (packs) should be treated as immutable binaries.
+		- **Programmatically generated files** (e.g., `.asd`) should be excluded since Live will recreate them.
+	- ## File Types & Internal Structure
+		- {{embed [[Ableton/File/.als]]}}
+		- {{embed [[Ableton/File/.alc]]}}
+		- {{embed [[Ableton/File/.adg]]}}
+		- {{embed [[Ableton/File/.adv]]}}
+		- {{embed [[Ableton/File/.amxd]]}}
+		- {{embed [[Ableton/File/.ask]]}}
+		- {{embed [[Ableton/File/.alp]]}}
+		- {{embed [[Ableton/File/.asd]]}}
+		- {{embed [[Ableton/File/.ams]]}}
+		- {{embed [[Ableton/File/.agr]]}}
+	- ## Misconceptions
+		- **Myth**: All Ableton files are binary and unsuitable for Git.  
+		  **Reality**: Many are gzipped XML or JSON and can be made git-friendly with filters.
+		- **Myth**: `.asd` files must be backed up.  
+		  **Reality**: They’re metadata caches and should be ignored in source control.
+	- ## Recommendations for Git
+		- **Store with filters**: `.als`, `.alc`, `.adg`, `.adv`, `.amxd`, `.ask`.
+		- **Ignore**: `.asd` (auto-regenerated).
+		- **Store as binary**: `.alp`, `.ams`, `.agr` (no useful diffs).
+		- **Use custom diff drivers**:
+			- `.als`/`.alc`/`.adg`/`.adv`: `gzip -cd`.
+			- `.amxd`: strip header, parse JSON.
+			- `.ask`: plain XML diff.
+	- ## See Also
+		- [[Person/Zack Steinkamp/blog/posts/2022-02-15-git-diff-amxd-max]]
+		- [[GitHub/codekiln/ableton-live-git-hooks]]
diff --git a/pages/Ableton___File___.adg.md b/pages/Ableton___File___.adg.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.adg]]
+
+- **Purpose**: Device Group (Rack preset).
+- **Format**: gzipped XML.
+- **Git**: Store; use `gzip -cd` filter for text diffs.
diff --git a/pages/Ableton___File___.adv.md b/pages/Ableton___File___.adv.md
@@ -1,2 +1,5 @@
-# `.adv` file suffix - Ableton Device
-	- This can include a whole [[Ableton/Instrument/Rack]]
+alias:: [[Ableton/File/.adv]]
+
+- **Purpose**: Device Preset (single Instrument/Effect preset).
+- **Format**: likely gzipped XML (similar to `.adg`).
+- **Git**: Store; verify format. Use same filter strategy as `.adg`.
diff --git a/pages/Ableton___File___.agr.md b/pages/Ableton___File___.agr.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.agr]]
+
+- **Purpose**: Groove File (timing/humanization template).
+- **Format**: binary.
+- **Git**: Store if custom grooves are central to project; diffs not possible.
diff --git a/pages/Ableton___File___.alc.md b/pages/Ableton___File___.alc.md
@@ -0,0 +1,7 @@
+alias:: [[Ableton/File/.alc]]
+
+- **Purpose**: Live Clip (saved audio or MIDI clip + device chain).
+- **Format**: gzipped XML.
+- **Git**: Same as `.als`. Useful to store; enables clip reuse and diffs.
+- **See Also:**
+	- [[GitHub/codekiln/ableton-live-git-hooks]]
diff --git a/pages/Ableton___File___.alp.md b/pages/Ableton___File___.alp.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.alp]]
+
+- **Purpose**: Live Pack (compressed bundle of sets, samples, presets).
+- **Format**: zipped archive.
+- **Git**: Treat as binary. Store only released versions; not suitable for diffs.
diff --git a/pages/Ableton___File___.als.md b/pages/Ableton___File___.als.md
@@ -0,0 +1,8 @@
+alias:: [[Ableton/File/.als]]
+
+- **Purpose**: Live Set (entire project/arrangement).
+- **Format**: gzipped XML.
+- **Speculation**: Unzipping yields structured XML with tracks, devices, automation.
+- **Git**: Store in repo. Use a `textconv` filter to decompress for diffs.
+- **See-Also:**
+	- [[GitHub/codekiln/ableton-live-git-hooks]]
diff --git a/pages/Ableton___File___.ams.md b/pages/Ableton___File___.ams.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.ams]]
+
+- **Purpose**: Ableton Meta Sound (Operator waveforms for Sampler/Simpler).
+- **Format**: binary.
+- **Git**: Store only if custom waveforms are part of creative assets; otherwise ignore.
diff --git a/pages/Ableton___File___.amxd.md b/pages/Ableton___File___.amxd.md
@@ -0,0 +1,6 @@
+alias:: [[c74/M4L/.amxd]]
+
+- **Purpose**: Max for Live Device (custom patch).
+- **Format**: JSON with a non-JSON binary header.
+- **Git**: Store; configure Git diff driver to skip header (e.g. `awk '(NR>1)'`). This exposes JSON for readable diffs.
+- **See Also**: [[Person/Zack Steinkamp/blog/posts/2022-02-15-git-diff-amxd-max]]
diff --git a/pages/Ableton___File___.asd.md b/pages/Ableton___File___.asd.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.asd]]
+
+- **Purpose**: Sample Analysis File (tempo, warp markers, waveform cache).
+- **Format**: binary metadata.
+- **Git**: Do not store; regenerated by Live.
diff --git a/pages/Ableton___File___.ask.md b/pages/Ableton___File___.ask.md
@@ -0,0 +1,5 @@
+alias:: [[Ableton/File/.ask]]
+
+- **Purpose**: Live Skin (UI color theme).
+- **Format**: XML.
+- **Git**: Store; Git can diff directly.
diff --git a/pages/Person___Zack Steinkamp___blog___posts___2022-02-15-git-diff-amxd-max.md b/pages/Person___Zack Steinkamp___blog___posts___2022-02-15-git-diff-amxd-max.md
@@ -1,14 +1,39 @@
 tags:: [[c74/M4L]]
+created-by:: [[Person/Zack Steinkamp]]
 
 - # [Making 'git diff' Work For .amxd](https://steinkamp.us/posts/2022-02-15-git-diff-amxd-max)
-	- id:: 67a8be1a-780f-4c61-82e5-c04cfae63cc6
-	  > `.amxd` files are basically JSON, but with a non-JSON file header. This binary part at the beginning makes git fall back to binary file mode when trying to show diffs. Usualy that's not very helpful.
-	- `echo '*.amxd binary diff=amxd' > ~/.gitattributes`
-	- `git config --global core.attributesfile ~/.gitattributes`
-	- then, in `~/.gitconfig`
-		- ```
+	- [[My Notes]]
+		- See also the source material at [steinkamp.us/pages/posts/2022-02-15-git-diff-amxd-max.md at main · zsteinkamp/steinkamp.us · GitHub](https://github.com/zsteinkamp/steinkamp.us/blob/main/pages/posts/2022-02-15-git-diff-amxd-max.md)
+	- #Quotes
+		- Here's a quick tip if you're using git for revision control in developing Max/MSP or Max For Live devices.
+		- Perhaps you have been here?
+		- ```bash
+		  $ git diff
+		  diff --git a/cool.amxd b/cool.amxd
+		  index c7a9b88..afdafb1 100644
+		  Binary files a/cool.amxd and b/cool.amxd differ
+		  ```
+		- `.amxd` files are basically JSON, but with a non-JSON file header. This binary part at the beginning makes git fall back to binary file mode when trying to show diffs. Usualy that's not very helpful.
+		  
+		  There's just a bit of configuration to make the `git diff` output more helpful. Here's what to do:
+		- 1. Create a global `.gitattributes` file in your home directory. This will will map the `.amxd` file extension to a named file type that we will use later. Run this command to create the file with the correct contents:
+		- ```bash
+		  echo '*.amxd binary diff=amxd' > ~/.gitattributes
+		  ```
+		- 2. Now tell git where to find the new global `.gitattributes` file. Run this command:
+		- ```bash
+		  git config --global core.attributesfile ~/.gitattributes
+		  ```
+		- 3. The final step is to tell git how to convert the 'binary' file to text when displaying a diff. Add this content to your `~/.gitconfig` file:
+		- ```config
+		  [diff "amxd"]
+		    textconv = awk '(NR>1)'
+		    binary = true
+		  ```
+		- 3. The final step is to tell git how to convert the 'binary' file to text when displaying a diff. Add this content to your `~/.gitconfig` file:
+		- ```config
 		  [diff "amxd"]
 		    textconv = awk '(NR>1)'
 		    binary = true
 		  ```
-	- > In this case, we're using `awk` to suppress printing the first line. That's good enough for my uses, but if you are an `awk` wizard and you want to use a tool like `jq` to work with the JSON data, perhaps you can suppress everything to the initial `{` on that first line.
+		- In this case, we're using `awk` to suppress printing the first line. That's good enough for my uses, but if you are an `awk` wizard and you want to use a tool like `jq` to work with the JSON data, perhaps you can suppress everything to the initial `{` on that first line.
diff --git a/pages/Person___codekiln___GitHub___alits.md b/pages/Person___codekiln___GitHub___alits.md
@@ -210,7 +210,7 @@ tags:: [[c74/M4L/Idea/Alits]]
 					  :END:
 						- I tried creating `apps/maxmsp-test/maxmsp-test.amxd` with a [[c74/max/obj/js]] as `js ./Code/Main.js`, and got `js: can't find file ./Code/Main.js`, even though `apps/maxmsp-test/Code/Main.js` exists
 							- I also tried `js Code/Main.js` which also did not work
-						- I wish there was a way to open [[c74/M4L/.amxd]] files ... there probably is because [[Person/Zack Steinkamp/blog/posts/2022-02-15-git-diff-amxd-max]] says ((67a8be1a-780f-4c61-82e5-c04cfae63cc6))
+						- I wish there was a way to open [[c74/M4L/.amxd]] files ... there probably is because [[Person/Zack Steinkamp/blog/posts/2022-02-15-git-diff-amxd-max]] says > `.amxd` files are basically JSON, but with a non-JSON file header. This binary part at the beginning makes git fall back to binary file mode when trying to show diffs. Usualy that's not very helpful.
 							- I imagine it might be able to adjust the paths if I was able to adjust the .amxd directly ...
 						- #Discovered that if I go to [[c74/max/Menu/File/Show File Browser]] I'm taken to [[c74/max/File Browser]] window, which lets one create [[c74/max/Collections]] of files. interesting. I tried adding `apps/maxmsp-test/Code/Main.js` to the file paths, but got "no new files have been added to the search path" because the extension is invalid. So that probably won't work.
 					- DONE is there some way that the [[c74/M4L/.amxd]] could be extracted into [[json]], and then we could add the multiple file paths into the .amxd directly? see [[c74/M4L/.amxd/How To/Decompile .amxd into json]]

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+## Audio`
	`2`	`+ - [[Ableton/File]]`
	`3`	`+ - [[Ableton/File/Concept/Storing in Git]]`