CSV Import Requirements

Overview

Importing your media files and text notes in bulk is a powerful way to quickly populate your Speak account. By following a few simple formatting rules for your CSV file, you can ensure a smooth and accurate import process, saving you time and effort.

A correctly formatted CSV file prevents errors and ensures that all your content is processed as intended, making it easier to manage and access your information within Speak.

How It Works

Speak uses a CSV (Comma Separated Values) file to understand how to import your content. Each row in the CSV represents a piece of content (like an audio file or a text note), and the columns tell Speak what information to associate with that content, such as its location, title, or tags.

CSV Format Basics

To successfully bulk import files into Speak, your CSV (Comma Separated Values) file must adhere to specific formatting rules. A correctly formatted CSV ensures that all your media files or text notes are processed accurately.

Header Row: The first row of your file MUST contain the column names (headers). These headers tell the system what data is in each column.
Standard Encoding: Save your CSV file with UTF-8 encoding to ensure special characters are displayed correctly.
File Size: For extremely large import jobs, consider breaking your CSV into smaller batches of 1000 rows to ensure smooth processing.

Required Columns (By Type)

The columns required in your CSV depend on whether you are uploading Audio/Video files or Text Notes.

For Audio & Video Files:

url (Required): The direct download link, YouTube URL, or Vimeo URL for the media file. The system must be able to access this link to download and process the file.

For Text Notes:

text (Required): The actual body content of the text note you want to create.

Optional Columns

You can include these additional columns to add metadata to your uploads:

name: The title of the file or note in Speak. If omitted, a default name will be generated.
description: A brief description of the file.
tags: A comma-separated list of tags to categorize your file (e.g., "Interview, research, 2023").
folderId: The specific ID of the Speak folder where you want the files to be stored.
sourceLanguage: The language code for the file (e.g., "en-US", "fr-FR").
createdAt: The creation date/time of the file (ISO format preferred).

Custom Fields

If you have set up Custom Fields in your Speak account, you can map data to them during CSV upload.

Header Name: Use the exact ID of your Custom Field as the column header.
Data Validation: Ensure the data in these columns matches the field type:
- Number Fields: Must contain only numeric values.
- Boolean Fields: Must be "true" or "false".
- URL Fields: Must be a valid link including "https://".
- Date Fields: Must be a valid date format.

Troubleshooting Common Errors

Here is a guide to resolving the most frequent errors encountered during CSV uploads.

Error	Cause	Solution
"No URL found"	The "url" column is missing or empty for a row in your media CSV.	Check your CSV and ensure every row has a valid link in the "url" column.
"Text not found"	The "text" column is missing or empty for a row in your text notes CSV.	Ensure the "text" column is populated for every row.
"Original file already exists in the folder"	Speak detects that a file with the same source URL has already been uploaded to the specific folder.	Remove the duplicate row from your CSV, or if you intend to re-upload, delete the original file from the folder first.
"Duration not found"	The system could not read the media file from the provided URL, often because the link is broken, expired, or requires a login.	Verify that the direct download link is publicly accessible and points directly to a media file.
"YouTube Data info not found" / "Vimeo Data info not found"	The YouTube or Vimeo link provided is invalid, private, or the video has been deleted.	Check the link in a browser incognito window to ensure it is publicly accessible.
"Invalid [FieldType] field"	Data in a custom field column does not match the required format (e.g., text in a Number field).	Review the specific column mentioned in the error and correct the formatting to match the field type (e.g., change "Yes" to "true" for Boolean fields).
"User has utilized all your available text notes..."	Your account has reached its limit for text note processing.	You may need to upgrade your plan or add balance to continue processing.

Next Steps

If you continue to experience issues after checking these requirements, please contact our support team with a copy of your CSV file (or a sample of it) for further assistance.

Ready to get started? Here's what to do next: