Skip to content

Commit 1c24503

Browse files
CSourcesCSources
committed
Updated documentation for Event Objects, Track Object, and Installation instructions; added details for Marker and Video events, and symlink development tips.
1 parent a87b307 commit 1c24503

5 files changed

Lines changed: 105 additions & 10 deletions

File tree

‎docs/host/interfaces.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Each interface defines a set of required callbacks or properties that must be pr
4343

4444
Registers classes dynamically at runtime via `this.classes` and `this.version`. Uses `CodeResource:Executable` in `metainfo.xml` instead of `classfactory.xml`. Requires defining `CCLGetClassFactory(codeResource)` as a global function — the host calls it on package load and expects an object implementing `IClassFactory`.
4545

46-
The host calls `createInstance(classID)` for `FrameworkService` class registrations. Other categories (`EditTask`, `Toolset`, etc.) are registered but not auto-instantiated — instances can be created manually via `factory.createInstance()`.
46+
The host calls `createInstance(classID)` for `FrameworkService` class registrations. Other categories (`EditTask`, etc.) are registered but not auto-instantiated — call `createInstance(classID)` on your factory object to create instances manually.
4747

4848
**Properties:**
4949

‎docs/objects/event_object.md‎

Lines changed: 53 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ Objects returned by iterators (`context.iterator`, `context.editor.activeRegion.
1212
- **[Instrument Part](#instrument-part-events)** — arrangement surface with `mediaType="Music"`. For the note-container surface, see [Region Object](region_object.md).
1313
- **[Pattern event](#pattern-events)** — arrangement surface with `mediaType="Pattern"`.
1414
- **[Lyrics](#lyrics-events)** — attached to MIDI notes, accessed via `getLyricsForNote(note)`.
15+
- **[Marker event](#marker-events)** — marker event on the Marker Track.
1516
- **[MIDI note](#midi-notes)** — has `pitch` and `velocity`, lives inside an Instrument Part (`.region`).
17+
- **[Video event](#video-events)** — video clip events with `mediaType="Video"`.
1618

1719
## Arranger Events
1820

@@ -29,7 +31,7 @@ Accessed via `context.iterator` or `context.editor.selection.newIterator()` on t
2931
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object. |
3032
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
3133
| `timeContext` | `object` - [timeContext Object](#timecontext-object)| No | — | Time context for conversions. |
32-
| `timeFormat` | `number` | No | `2` | Time format identifier. |
34+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
3335

3436
| Method | Returns | Parameters | Description |
3537
|---|---|---|---|
@@ -51,7 +53,7 @@ Accessed via `context.iterator` or `context.editor.selection.newIterator()` in t
5153
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object. |
5254
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
5355
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context for conversions. |
54-
| `timeFormat` | `number` | No | `0` | Time format identifier. |
56+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
5557

5658
| Method | Returns | Parameters | Description |
5759
|---|---|---|---|
@@ -73,7 +75,7 @@ Accessed via `context.iterator` or `context.editor.selection.newIterator()` on t
7375
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
7476
| `chord` | `object` [Chord Data Object](#chord-data-object) | No | — | Chord data sub-object (see below). |
7577
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context for conversions. |
76-
| `timeFormat` | `number` | No | `2` | Time format identifier. |
78+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
7779

7880
| Method | Returns | Parameters | Description |
7981
|---|---|---|---|
@@ -142,7 +144,7 @@ Accessed via `context.iterator` or `context.editor.selection.newIterator()` when
142144
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object. |
143145
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
144146
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context for conversions. |
145-
| `timeFormat` | `number` | No | `2` | Time format identifier. |
147+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
146148
| `parent` | `object` | No | — | Parent object. |
147149

148150
| Method | Returns | Parameters | Description |
@@ -171,7 +173,7 @@ Accessed via `context.iterator` or `context.editor.selection.newIterator()` when
171173
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object. |
172174
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
173175
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context for conversions. |
174-
| `timeFormat` | `number` | No | `2` | Time format identifier. |
176+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
175177
| `parent` | `object` | No | — | Parent object. |
176178

177179
| Method | Returns | Parameters | Description |
@@ -201,6 +203,25 @@ if (lyrics) {
201203
}
202204
```
203205

206+
## Marker Events
207+
208+
Accessed via `context.iterator` or `context.editor.selection.newIterator()` on the Marker Track when selected markers are available. Markers are point events — `startTime` and `endTime` represent the same position, and `length` is always `0`.
209+
210+
| Property | Type | Writable | Example | Description |
211+
|---|---|---|---|---|
212+
| `name` | `string` | No | `"Hit"` | Marker label. |
213+
| `color` | `number` | No | `0` | Marker color as integer. |
214+
| `start` | `number` | No | `1.75` | Start position in beats. |
215+
| `length` | `number` | No | `0` | Always `0` — markers are point events. |
216+
| `offset` | `number` | No | `0` | Offset value. |
217+
| `startTime` | `object` - [Time Object](time_object.md) | No | — | Start time object (marker position). |
218+
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object (same as `startTime`). |
219+
| `parent` | `object` | No | — | The Marker Track. Same object as `getTrack()`. |
220+
221+
| Method | Returns | Parameters | Description |
222+
|---|---|---|---|
223+
| `getTrack()` | `object` | none | Returns the Marker Track. |
224+
204225
## MIDI Notes
205226

206227
Accessed via `context.iterator` from the Note Editor in a [MusicEdit](../package_structure/classfactory.md#subcategory-values) context when selected notes are available. `context.editor.activeRegion.createSequenceIterator()` also provides all notes in the selected region.
@@ -219,7 +240,7 @@ Accessed via `context.iterator` from the Note Editor in a [MusicEdit](../package
219240
| `lengthTime` | `object` [Time Object](time_object.md) | No | — | Duration time object. |
220241
| `region` | `object` - [Region Object](region_object.md) | No | — | Containing Instrument Part. |
221242
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context (`secondsToPpq()`, `ppqToSeconds()`, `getBarStart()`). |
222-
| `timeFormat` | `number` | No | `2` | Time format identifier. |
243+
| `timeFormat` | `number` | No | `2` | Timebase. `2` = Beats, `0` = Seconds. |
223244

224245
| Method | Returns | Parameters | Description |
225246
|---|---|---|---|
@@ -228,6 +249,32 @@ Accessed via `context.iterator` from the Note Editor in a [MusicEdit](../package
228249
| `previousEvent()` | `object` - [MIDI Note](#midi-notes) | none | Previous event in the region sequence. |
229250
| `globalToRegionData(pos)` | `number` | `pos` ([Time Object](time_object.md), req): Time position. | Converts global time coordinates to region-local data. |
230251

252+
## Video Events
253+
254+
Accessed via `context.iterator` or `context.editor.selection.newIterator()` in the TrackEdit context when a video event on the Video Track is selected. Video events share the same base timing surface as audio events with `mediaType="Video"`.
255+
256+
| Property | Type | Writable | Example | Description |
257+
|---|---|---|---|---|
258+
| `name` | `string` | No | `"video_name"` | Video event name. |
259+
| `color` | `number` | No | `2434491` | Event color as integer. |
260+
| `mediaType` | `string` | No | `"Video"` | Identifies this as a video event. |
261+
| `isMuted` | `number` | No | `0` | `1` if muted. |
262+
| `start` | `number` | No | `17.49` | Start position in beats. |
263+
| `length` | `number` | No | `138.29` | Duration in beats. |
264+
| `offset` | `number` | No | `11.81` | Offset value. |
265+
| `startTime` | `object` - [Time Object](time_object.md) | No | — | Start time object. |
266+
| `endTime` | `object` - [Time Object](time_object.md) | No | — | End time object. |
267+
| `lengthTime` | `object` - [Time Object](time_object.md) | No | — | Duration time object. |
268+
| `timeContext` | `object` - [timeContext Object](#timecontext-object) | No | — | Time context for conversions. |
269+
| `timeFormat` | `number` | No | `0` | Timebase — always Seconds (`0`). |
270+
| `parent` | `object` | No | — | The Video Track. Same object as `getTrack()`. |
271+
272+
| Method | Returns | Parameters | Description |
273+
|---|---|---|---|
274+
| `getRoot()` | `object` | none | Returns the root region. |
275+
| `getTrack()` | `object` | none | Returns the containing Video Track. |
276+
| `globalToRegionData(pos)` | `number` | `pos` ([Time Object](time_object.md), req): Time position. | Converts global time coordinates to region-local data. |
277+
231278
## timeContext Object
232279

233280
Accessed via the `.timeContext` property on any event.

‎docs/objects/track_object.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,7 @@ The `.layers` property on a track. Present on all track types.
4848
| Method | Returns | Parameters | Description |
4949
|---|---|---|---|
5050
| `getTrack()` | `object` | none | Returns the track object itself (identity reference). |
51-
| `isEmpty()` | `number` | none | Returns `0` if the track has content, `1` if empty. |
51+
| `isEmpty()` | `number` | none | Returns `0` if the track has content, `1` if empty. |
52+
| `createIterator()` | `object` - [Region Object](region_object.md) / [Audio Event](event_object.md#audio-events) | none | Creates an iterator over the regions/events on this track. |
53+
| `getLayer()` | `object` | none | Returns the track's layer object. |
54+
| `getLayerIndex()` | `number` | none | Returns the current layer index. |

‎docs/package_structure/installation.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,44 @@ Install script packages into Studio Pro's `Scripts` folder:
1010
| **Windows** | `C:\Program Files\Fender\Studio Pro 8\Scripts\` |
1111
| **macOS** | `/Applications/Studio Pro 8.app/Contents/Scripts/` |
1212

13+
**Note:** Scripts aren't retained when updating Studio Pro. Backup your scripts before updating.
14+
15+
<details>
16+
17+
<summary>Accessing macOS scripts folder</summary>
18+
19+
- Open Finder.
20+
- Select the **Applications** folder.
21+
- Right-click the **Studio Pro 8** application.
22+
- Select **'Show Package Contents'**.
23+
24+
</details>
25+
1326
## Initial recognition
1427

1528
Studio Pro scans scripts on startup. If Studio Pro is already open when you install a new package, restart the application so it picks up the new script(s).
1629

1730
## Hot-reloading behavior
1831

19-
For script dialogs, replacing the contents of an installed package can hot-swap script source files, `skin.xml`, and `metainfo.xml` changes when the script is reopened. `classfactory.xml` registration changes still require a restart. For AddIn scripts, a restart is always required to reflect changes as these are scanned at runtime.
32+
For script dialogs, replacing the contents of an installed package can hot-swap script source files, `skin.xml`, and `metainfo.xml` changes when the script is reopened. `classfactory.xml` registration changes still require a restart. For AddIn scripts, a restart is always required to reflect changes as these are scanned at runtime.
33+
34+
## Development Tip (symlink)
35+
36+
For faster iteration, symlink a script folder from your project directory into the `Scripts` folder instead of constantly copying files over:
37+
38+
### macOS
39+
40+
Open **Terminal**, then use:
41+
42+
```bash
43+
ln -s "/path/to/my-script" \
44+
"/Applications/Studio Pro 8.app/Contents/Scripts/my-script"
45+
```
46+
47+
### Windows
48+
49+
Open **Command Prompt** as Administrator, then use:
50+
51+
```cmd
52+
mklink /D "C:\Program Files\Fender\Studio Pro 8\Scripts\my-script" "C:\path\to\my-script"
53+
```

‎docs/scripts/installation.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,15 @@ sidebar_position: 2
99
| **Windows** | `C:\Program Files\Fender\Studio Pro 8\Scripts\` |
1010
| **macOS** | `/Applications/Studio Pro 8.app/Contents/Scripts/` |
1111

12-
Place the `.package` in your Studio Pro scripts folder. Restart Studio Pro after installing.
12+
Place the `.package` in your Studio Pro scripts folder. Restart Studio Pro after installing. **Note:** Scripts aren't retained when updating Studio Pro. Backup your scripts before updating.
13+
14+
<details>
15+
16+
<summary>Accessing macOS scripts folder</summary>
17+
18+
- Open Finder.
19+
- Select the **Applications** folder.
20+
- Right-click the **Studio Pro 8** application.
21+
- Select **'Show Package Contents'**.
22+
23+
</details>

0 commit comments

Comments
 (0)