0
# Profile Import
1

2
Core profile importing functionality supporting automatic format detection and parsing for 15+ profiler formats from various programming languages and environments.
3

4
## Capabilities
5

6
### Main Import Functions
7

8
Primary entry points for importing profile data from different sources.
9

10
```typescript { .api }
11
/**
12
 * Import profile from text content with automatic format detection
13
 * @param fileName - Name of the profile file for format detection
14
 * @param contents - Raw text content of the profile
15
 * @returns Promise resolving to ProfileGroup or null if format unsupported
16
 */
17
function importProfileGroupFromText(
18
  fileName: string,
19
  contents: string
20
): Promise<ProfileGroup | null>;
21

22
/**
23
 * Import profile from base64-encoded data
24
 * @param fileName - Name of the profile file for format detection
25
 * @param b64contents - Base64-encoded profile data
26
 * @returns Promise resolving to ProfileGroup or null if format unsupported
27
 */
28
function importProfileGroupFromBase64(
29
  fileName: string,
30
  b64contents: string
31
): Promise<ProfileGroup | null>;
32

33
/**
34
 * Import profile from browser File object
35
 * @param file - File object containing profile data
36
 * @returns Promise resolving to ProfileGroup or null if format unsupported
37
 */
38
function importProfilesFromFile(file: File): Promise<ProfileGroup | null>;
39

40
/**
41
 * Import profile from ArrayBuffer
42
 * @param fileName - Name of the profile file for format detection
43
 * @param buffer - ArrayBuffer containing profile data
44
 * @returns Promise resolving to ProfileGroup or null if format unsupported
45
 */
46
function importProfilesFromArrayBuffer(
47
  fileName: string,
48
  buffer: ArrayBuffer
49
): Promise<ProfileGroup | null>;
50

51
/**
52
 * Import profiles from FileSystem Directory Entry (for Instruments traces)
53
 * @param entry - FileSystemDirectoryEntry containing trace data
54
 * @returns Promise resolving to ProfileGroup or null if import fails
55
 */
56
function importFromFileSystemDirectoryEntry(
57
  entry: FileSystemDirectoryEntry
58
): Promise<ProfileGroup | null>;
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { 
65
  importProfileGroupFromText,
66
  importProfilesFromFile,
67
  importProfileGroupFromBase64 
68
} from 'speedscope/dist/import';
69

70
// Import from text content
71
const textProfile = await importProfileGroupFromText(
72
  'profile.stackprof.json',
73
  jsonString
74
);
75

76
// Import from File object (browser file input)
77
const fileInput = document.querySelector('input[type="file"]');
78
const file = fileInput.files[0];
79
const fileProfile = await importProfilesFromFile(file);
80

81
// Import from base64 data
82
const base64Profile = await importProfileGroupFromBase64(
83
  'profile.chrome.json',
84
  base64String
85
);
86
```
87

88
### Chrome DevTools Import
89

90
Import profiles from Chrome DevTools performance panel and CPU profiler.
91

92
```typescript { .api }
93
/**
94
 * Import from Chrome CPU profile format
95
 * @param profile - Chrome CPU profile object
96
 * @returns Profile instance or null
97
 */
98
function importFromChromeCPUProfile(profile: any): Profile | null;
99

100
/**
101
 * Import from Chrome Timeline trace format
102
 * @param events - Array of trace events or timeline object
103
 * @param fileName - Optional filename for profile naming
104
 * @returns ProfileGroup or null
105
 */
106
function importFromChromeTimeline(
107
  events: any[] | any,
108
  fileName?: string
109
): ProfileGroup | null;
110

111
/**
112
 * Import from legacy V8 CPU profile format
113
 * @param profile - Old V8 CPU profile object
114
 * @returns Profile instance or null
115
 */
116
function importFromOldV8CPUProfile(profile: any): Profile | null;
117

118
/**
119
 * Import from Chrome heap profile format
120
 * @param profile - Chrome heap profile object
121
 * @returns Profile instance or null
122
 */
123
function importFromChromeHeapProfile(profile: any): Profile | null;
124

125
/**
126
 * Check if data matches Chrome Timeline format
127
 * @param data - Data to check
128
 * @returns Boolean indicating if data is Chrome Timeline
129
 */
130
function isChromeTimeline(data: any): boolean;
131

132
/**
133
 * Check if data matches Chrome Timeline object format
134
 * @param data - Data to check
135
 * @returns Boolean indicating if data is Chrome Timeline object
136
 */
137
function isChromeTimelineObject(data: any): boolean;
138
```
139

140
### V8 Profiler Import
141

142
Import profiles from V8 JavaScript engine profiler outputs.
143

144
```typescript { .api }
145
/**
146
 * Import from V8 --prof-process log format
147
 * @param profile - V8 profiler log object
148
 * @returns Profile instance or null
149
 */
150
function importFromV8ProfLog(profile: any): Profile | null;
151
```
152

153
### Ruby Profiler Import
154

155
Import profiles from Ruby profiling tools.
156

157
```typescript { .api }
158
/**
159
 * Import from Ruby stackprof format
160
 * @param profile - Stackprof profile object
161
 * @returns Profile instance or null
162
 */
163
function importFromStackprof(profile: any): Profile | null;
164
```
165

166
### Firefox Profiler Import
167

168
Import profiles from Firefox Developer Tools profiler.
169

170
```typescript { .api }
171
/**
172
 * Import from Firefox profiler format
173
 * @param profile - Firefox profile object
174
 * @returns Profile instance or null
175
 */
176
function importFromFirefox(profile: any): Profile | null;
177
```
178

179
### macOS Instruments Import
180

181
Import profiles from macOS Instruments application.
182

183
```typescript { .api }
184
/**
185
 * Import from Instruments deep copy text format
186
 * @param contents - Instruments deep copy text content
187
 * @returns Profile instance or null
188
 */
189
function importFromInstrumentsDeepCopy(contents: any): Profile | null;
190

191
/**
192
 * Import from Instruments trace directory
193
 * @param entry - FileSystemDirectoryEntry of trace directory
194
 * @returns Promise resolving to ProfileGroup or null
195
 */
196
function importFromInstrumentsTrace(
197
  entry: FileSystemDirectoryEntry
198
): Promise<ProfileGroup | null>;
199
```
200

201
### Go pprof Import
202

203
Import profiles from Go's pprof profiler.
204

205
```typescript { .api }
206
/**
207
 * Import from protobuf-encoded pprof format
208
 * @param buffer - ArrayBuffer containing pprof data
209
 * @returns Profile instance or null
210
 */
211
function importAsPprofProfile(buffer: ArrayBuffer): Profile | null;
212
```
213

214
### Linux Perf Import
215

216
Import profiles from Linux perf tools.
217

218
```typescript { .api }
219
/**
220
 * Import from Linux perf script output
221
 * @param contents - Perf script text content
222
 * @returns ProfileGroup or null
223
 */
224
function importFromLinuxPerf(contents: any): ProfileGroup | null;
225
```
226

227
### Collapsed Stack Format Import
228

229
Import profiles from collapsed stack format (used by FlameGraph tools).
230

231
```typescript { .api }
232
/**
233
 * Import from collapsed stack format
234
 * @param contents - Collapsed stack text content
235
 * @returns Profile instance or null
236
 */
237
function importFromBGFlameGraph(contents: any): Profile | null;
238
```
239

240
### Safari Profiler Import
241

242
Import profiles from Safari Web Inspector.
243

244
```typescript { .api }
245
/**
246
 * Import from Safari timeline recording format
247
 * @param profile - Safari recording object
248
 * @returns Profile instance or null
249
 */
250
function importFromSafari(profile: any): Profile | null;
251
```
252

253
### Additional Format Support
254

255
Support for various other profiler formats.
256

257
```typescript { .api }
258
/**
259
 * Import from Callgrind profile format
260
 * @param contents - Callgrind profile content
261
 * @param fileName - Profile filename
262
 * @returns ProfileGroup or null
263
 */
264
function importFromCallgrind(contents: any, fileName: string): ProfileGroup | null;
265

266
/**
267
 * Import from Haskell GHC JSON profile format
268
 * @param profile - Haskell profile object
269
 * @returns ProfileGroup or null
270
 */
271
function importFromHaskell(profile: any): ProfileGroup | null;
272

273
/**
274
 * Import from Papyrus profile format
275
 * @param contents - Papyrus profile content
276
 * @returns Profile instance or null
277
 */
278
function importFromPapyrus(contents: any): Profile | null;
279

280
/**
281
 * Import from PMC stat callgraph format
282
 * @param contents - PMC stat callgraph content
283
 * @returns Profile instance or null
284
 */
285
function importFromPMCStatCallGraph(contents: any): Profile | null;
286

287
/**
288
 * Import from Trace Event Format
289
 * @param profile - Trace event format object
290
 * @returns ProfileGroup or null
291
 */
292
function importTraceEvents(profile: any): ProfileGroup | null;
293

294
/**
295
 * Check if data matches Trace Event Format
296
 * @param data - Data to check
297
 * @returns Boolean indicating if data is Trace Event Format
298
 */
299
function isTraceEventFormatted(data: any): boolean;
300
```
301

302
## Format Detection
303

304
Speedscope uses a two-pass detection system:
305

306
1. **Filename-based detection**: Checks file extensions and naming patterns
307
2. **Content-based detection**: Analyzes file structure and properties
308

309
### Supported File Patterns
310

311
- `.speedscope.json` - Native speedscope format
312
- `.chrome.json`, `Profile-*.json`, `Trace-*.json` - Chrome formats
313
- `.stackprof.json` - Ruby stackprof
314
- `.instruments.txt` - Instruments deep copy
315
- `.linux-perf.txt` - Linux perf output
316
- `.collapsedstack.txt` - Collapsed stack format
317
- `.v8log.json` - V8 profiler log
318
- `.heapprofile` - Chrome heap profiles
319
- `-recording.json` - Safari profiles
320
- `callgrind.*` - Callgrind format
321
- `.pmcstat.graph` - PMC stat format
322

323
## Types
324

325
```typescript { .api }
326
interface ProfileDataSource {
327
  name(): Promise<string>;
328
  readAsArrayBuffer(): Promise<ArrayBuffer>;
329
  readAsText(): Promise<TextProfileDataSource>;
330
}
331

332
class TextProfileDataSource {
333
  constructor(fileName: string, contents: string);
334
  parseAsJSON(): any;
335
  firstChunk(): string;
336
}
337

338
class MaybeCompressedDataReader implements ProfileDataSource {
339
  static fromFile(file: File): MaybeCompressedDataReader;
340
  static fromArrayBuffer(fileName: string, buffer: ArrayBuffer): MaybeCompressedDataReader;
341
}
342
```