0
# File Format
1

2
Export and import functionality for speedscope's native JSON file format with comprehensive metadata, event serialization, and schema validation.
3

4
## Capabilities
5

6
### Export Functions
7

8
Functions for exporting profile data to speedscope's native JSON format.
9

10
```typescript { .api }
11
/**
12
 * Export a profile group to speedscope's native JSON format
13
 * @param profileGroup - ProfileGroup containing profiles to export
14
 * @returns FileFormat.File object representing the complete export
15
 */
16
function exportProfileGroup(profileGroup: ProfileGroup): FileFormat.File;
17

18
/**
19
 * Save profile group to a downloadable file in the browser
20
 * @param profileGroup - ProfileGroup to save
21
 * @param fileName - Optional custom filename (defaults to profile name)
22
 */
23
function saveToFile(profileGroup: ProfileGroup, fileName?: string): void;
24
```
25

26
### Import Functions
27

28
Functions for importing speedscope's native JSON format.
29

30
```typescript { .api }
31
/**
32
 * Import profiles from speedscope JSON format
33
 * @param jsonData - Parsed JSON data in speedscope format
34
 * @returns ProfileGroup or null if import fails
35
 */
36
function importSpeedscopeProfiles(jsonData: any): ProfileGroup | null;
37
```
38

39
### File Format Specification
40

41
Complete type definitions for speedscope's native JSON file format.
42

43
```typescript { .api }
44
/**
45
 * Root file format interface for speedscope JSON files
46
 */
47
interface FileFormat.File {
48
  /** Schema URL for validation */
49
  $schema: 'https://www.speedscope.app/file-format-schema.json';
50
  
51
  /** Shared data used across all profiles */
52
  shared: {
53
    /** Array of frame definitions referenced by profiles */
54
    frames: FileFormat.Frame[];
55
  };
56
  
57
  /** Array of profile definitions */
58
  profiles: FileFormat.Profile[];
59
  
60
  /** Optional name for the profile group */
61
  name?: string;
62
  
63
  /** Index of profile to display by default (0-based) */
64
  activeProfileIndex?: number;
65
  
66
  /** Name and version of the tool that exported this file */
67
  exporter?: string;
68
}
69

70
/**
71
 * Frame definition in the file format
72
 */
73
interface FileFormat.Frame {
74
  /** Display name of the frame */
75
  name: string;
76
  
77
  /** Source file path (optional) */
78
  file?: string;
79
  
80
  /** Line number in source file (1-based, optional) */
81
  line?: number;
82
  
83
  /** Column number in source file (1-based, optional) */
84
  col?: number;
85
}
86

87
/**
88
 * Union type for different profile formats
89
 */
90
type FileFormat.Profile = FileFormat.EventedProfile | FileFormat.SampledProfile;
91

92
/**
93
 * Event-based profile format for timeline data
94
 */
95
interface FileFormat.EventedProfile {
96
  /** Profile type discriminator */
97
  type: FileFormat.ProfileType.EVENTED;
98
  
99
  /** Human-readable profile name */
100
  name: string;
101
  
102
  /** Unit for all timing values */
103
  unit: FileFormat.ValueUnit;
104
  
105
  /** Starting timestamp for the profile */
106
  startValue: number;
107
  
108
  /** Ending timestamp for the profile */
109
  endValue: number;
110
  
111
  /** Array of frame open/close events */
112
  events: (FileFormat.OpenFrameEvent | FileFormat.CloseFrameEvent)[];
113
}
114

115
/**
116
 * Sample-based profile format for periodic sampling
117
 */
118
interface FileFormat.SampledProfile {
119
  /** Profile type discriminator */
120
  type: FileFormat.ProfileType.SAMPLED;
121
  
122
  /** Human-readable profile name */
123
  name: string;
124
  
125
  /** Unit for all weight values */
126
  unit: FileFormat.ValueUnit;
127
  
128
  /** Starting timestamp for the profile */
129
  startValue: number;
130
  
131
  /** Ending timestamp for the profile */
132
  endValue: number;
133
  
134
  /** Array of call stacks, each element is array of frame indices */
135
  samples: number[][];
136
  
137
  /** Weight/duration for each sample (same length as samples array) */
138
  weights: number[];
139
}
140
```
141

142
### Profile Types and Events
143

144
Enums and interfaces for profile structure.
145

146
```typescript { .api }
147
/**
148
 * Enum for different profile types
149
 */
150
enum FileFormat.ProfileType {
151
  EVENTED = 'evented',
152
  SAMPLED = 'sampled'
153
}
154

155
/**
156
 * Enum for event types in evented profiles
157
 */
158
enum FileFormat.EventType {
159
  OPEN_FRAME = 'O',
160
  CLOSE_FRAME = 'C'
161
}
162

163
/**
164
 * Event indicating a stack frame was entered
165
 */
166
interface FileFormat.OpenFrameEvent {
167
  /** Event type discriminator */
168
  type: FileFormat.EventType.OPEN_FRAME;
169
  
170
  /** Timestamp when frame was entered */
171
  at: number;
172
  
173
  /** Index into the shared frames array */
174
  frame: number;
175
}
176

177
/**
178
 * Event indicating a stack frame was exited
179
 */
180
interface FileFormat.CloseFrameEvent {
181
  /** Event type discriminator */
182
  type: FileFormat.EventType.CLOSE_FRAME;
183
  
184
  /** Timestamp when frame was exited */
185
  at: number;
186
  
187
  /** Index into the shared frames array */
188
  frame: number;
189
}
190

191
/**
192
 * Supported units for profile values
193
 */
194
type FileFormat.ValueUnit = 
195
  | 'none'
196
  | 'nanoseconds'
197
  | 'microseconds' 
198
  | 'milliseconds'
199
  | 'seconds'
200
  | 'bytes';
201
```
202

203
**Usage Examples:**
204

205
```typescript
206
import { 
207
  exportProfileGroup, 
208
  saveToFile, 
209
  importSpeedscopeProfiles 
210
} from 'speedscope';
211

212
// Export profile group to JSON format
213
const profileGroup = {
214
  name: 'My Application Profile',
215
  indexToView: 0,
216
  profiles: [profile1, profile2]
217
};
218

219
const exportedData = exportProfileGroup(profileGroup);
220

221
// Save to file in browser
222
saveToFile(profileGroup, 'my-profile.speedscope.json');
223

224
// Import from JSON data
225
const jsonData = JSON.parse(jsonString);
226
const importedProfileGroup = importSpeedscopeProfiles(jsonData);
227

228
// Example exported file structure
229
const exampleFile: FileFormat.File = {
230
  $schema: 'https://www.speedscope.app/file-format-schema.json',
231
  exporter: 'speedscope@1.23.1',
232
  name: 'CPU Profile',
233
  activeProfileIndex: 0,
234
  shared: {
235
    frames: [
236
      { name: 'main', file: 'app.js', line: 1 },
237
      { name: 'helper', file: 'utils.js', line: 15 }
238
    ]
239
  },
240
  profiles: [{
241
    type: 'evented',
242
    name: 'Main Thread',
243
    unit: 'milliseconds',
244
    startValue: 0,
245
    endValue: 1000,
246
    events: [
247
      { type: 'O', at: 0, frame: 0 },
248
      { type: 'O', at: 100, frame: 1 },
249
      { type: 'C', at: 200, frame: 1 },
250
      { type: 'C', at: 1000, frame: 0 }
251
    ]
252
  }]
253
};
254
```
255

256
### File Format Schema
257

258
The speedscope file format includes a JSON schema for validation:
259

260
- **Schema URL**: `https://www.speedscope.app/file-format-schema.json`
261
- **Version Support**: Backward compatible across speedscope versions
262
- **Validation**: Files can be validated against the schema for correctness
263
- **Extensions**: Schema allows additional properties for future extensions
264

265
### Export Process
266

267
When exporting profiles, speedscope:
268

269
1. **Frame Deduplication**: Combines identical frames across profiles into shared array
270
2. **Index Mapping**: Maps frame references to indices in shared frames array  
271
3. **Event Serialization**: Converts call tree or sample data to event sequences
272
4. **Metadata Addition**: Adds exporter information, timestamps, and version data
273
5. **Schema Compliance**: Ensures output conforms to the JSON schema
274

275
### Import Process
276

277
When importing speedscope files, the system:
278

279
1. **Schema Validation**: Checks for required fields and proper structure
280
2. **Frame Reconstruction**: Rebuilds Frame objects from shared frames array
281
3. **Profile Reconstruction**: Recreates Profile objects from event data or samples
282
4. **Metadata Extraction**: Extracts names, units, and timing information
283
5. **ProfileGroup Assembly**: Combines profiles into a ProfileGroup structure
284

285
### File Naming Convention
286

287
Speedscope uses the `.speedscope.json` extension for native format files:
288

289
- **Detection**: Automatic format detection based on file extension
290
- **Priority**: `.speedscope.json` files are processed with highest priority
291
- **Schema**: Files with this extension must include the schema URL
292
- **Validation**: Extension indicates expectation of schema compliance
293

294
## Types
295

296
```typescript { .api }
297
// Type aliases for common file format operations
298
type SpeedscopeFile = FileFormat.File;
299
type SpeedscopeFrame = FileFormat.Frame;
300
type SpeedscopeProfile = FileFormat.Profile;
301

302
// Export function signatures
303
type ExportFunction = (profileGroup: ProfileGroup) => FileFormat.File;
304
type SaveFunction = (profileGroup: ProfileGroup, fileName?: string) => void;
305
type ImportFunction = (jsonData: any) => ProfileGroup | null;
306

307
// Event sequence types for evented profiles
308
type EventSequence = (FileFormat.OpenFrameEvent | FileFormat.CloseFrameEvent)[];
309
type SampleSequence = { samples: number[][], weights: number[] };
310
```