> For the complete documentation index, see [llms.txt](https://plugins.audacityteam.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plugins.audacityteam.org/contributing/developing-your-own-plugins-and-scripts/creating-your-own-nyquist-plugins/tutorials/the-scratch-symbol-tutorial.md).

# The \*SCRATCH\* Symbol Tutorial

\**SCRATCH\** is a global symbol, specific to Nyquist in Audacity, which is not deleted in-between plugin runs. It provides a way for information to survive from one invocation of a plugin to the next. However, you should not rely on the *"value"* of \*SCRATCH\* beyond a single invocation of a plugin as it could be overwritten by another plugin. It is better to use property lists of \*SCRATCH\*. That way, you get a whole name space rather than a single variable name, and with careful naming of the property keys, name collisions can be avoided.

To pass data from plugin "effectX-partA" to "effectX-partB":

1\. Assign a property name based on the effect name, e.g.: 'EFFECTX \[or in SAL, which does not support the single-quote notation of LISP, write QUOTE(EFFECTX). ]

2\. "effectX-partA" should delete any old property value:

```lisp
exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
(remprop '*SCRATCH* 'effectx) ;; in LISP
```

3\. "effectX-partA" should compute a new property value **v** and save it:

```lisp
 exec putprop(quote(*SCRATCH*), v, quote(effectx)) ;; in SAL
 (putprop '*SCRATCH* v 'effectx) ;; in LISP
```

4\. "effectX-partB" should access the property using:

```lisp
 set v = get(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (get '*SCRATCH* 'effectx) ;; in LISP
```

5\. When "effectX-partB" finishes, it should remove the property:

```lisp
 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (remprop '*SCRATCH* 'effectx) ;; in LISP
```

But there may be cases where you do some analysis and want to use the analysis data multiple times. You might even have multiple analysis plugins operating on different inputs to collect data to feed into a plugin with multiple inputs. In this case, which might be quite common, you should not call REMPROP(), but this has the problem of leaving data on the \*SCRATCH\* property list indefinitely.

In cases where \*SCRATCH\* data is not deleted immediately after use, and where there is the potential to leave large amounts of memory there, there should be another effect, e.g. "effectX-partCleanup", that simply calls:

```lisp
 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
 (remprop '*SCRATCH* 'effectx) ;; in LISP
```

allowing the user to explicitly free up any data stored on the 'EFFECTX property. It would be reasonable to omit the "effectX-partCleanup" effect if the data stored on the property list has a maximum size of, say, 10KB. The problem we want to avoid is properties with unbounded size getting left in the heap until Audacity is restarted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plugins.audacityteam.org/contributing/developing-your-own-plugins-and-scripts/creating-your-own-nyquist-plugins/tutorials/the-scratch-symbol-tutorial.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.