Video Resource¶

Represents a video on Amara.

Listing videos

GET /api2/partners/videos/¶

Query Parameters:

video_url – list only videos with the given URL, useful for finding out information about a video already on Amara. team – Only show videos that belong to a team identified by slug. project – Only show videos that belong to a project with the given slug. Passing in null will return only videos that don’t belong to a project. order_by – Applies sorting to the video list. Possible values: title: ascending -title: descending created: older videos first -created : newer videos

Creating Videos:

POST /api2/partners/videos/¶

Form Parameters:

video_url – The url for the video. Any url that Amara accepts will work here. You can send the URL for a file (e.g. http:///www.example.com/my-video.ogv) , or a link to one of our accepted providers (youtube, vimeo, dailymotion, blip.tv) title – The title for the video :form description: About this video duration – Duration in seconds primary_audio_language_code – The language code representing main language spoken on the video. This helps the UI to show the best title for that video, or set “Subtitle” taks in the right language from the get-go - optional.

When submitting URLs of external providers (i.e. youtube, vimeo), the metadata (title, description, duration) can be fetched from them. If you’re submitting a link to a file (mp4, flv) then you can make sure those attributes are set with these parameters. Note that these parameters do override any information from the original provider.

Information about a specific video can be retrieved from the URL:

Video Detail:

GET /api2/partners/videos/[video-id]/¶

The video listing resource already returns a resource_uri for each video to be used when retrieving the details.

Updating a video object:

PUT /api2/partners/videos/[video-id]/¶

With the same parameters for creation. Note that through out our system, a video cannot have it’s URLs changed. So you can change other video attributes (title, description) but the URL sent must be the same original one.

curl -i -X PUT -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \
    --data '{"team": "team_b"}' \
    https://host/api2/partners/videos/video-id/

{
    "team:" "team-slug",
    "project": "new-project"
}

{
    "all_urls": [
        "http://vimeo.com/4951380"
    ],
    "created": "2012-05-15T06:05:14",
    "description": "Concierto Grupo NOMOI \n(Torrevieja 17/05/2009)\nProyecto TRANSMOSFERA\nAcci\u00f3n interactiva de m\u00fasica, teatro e imagen.\nJuan Pablo Zaragoza - V\u00eddeo y Guitarra sintetizada\nJos\u00e9 Mar\u00eda Pastor - Electr\u00f3nica\nRaul Ferrandez - Voz y acci\u00f3n teatral",
    "duration": null,
    "id": "PUuHIcJ5mq5S",
    "languages": [],
    "original_language": null,
    "project": null,
    "resource_uri": "/api2/partners/videos/PUuHIcJ5mq5S/",
    "site_url": "http://unisubs.example.com:8000/videos/PUuHIcJ5mq5S/info/",
    "team": null,
    "thumbnail": "http://b.vimeocdn.com/ts/142/595/14259507_640.jpg",
    "title": "Concierto NOMOI (Torrevieja 17/05/2009)"
}

Video Language Resource¶

Represents a language for a given video on Amara.

Listing video languages:

GET /api2/partners/videos/[video-id]/languages/¶

Creating Video Languages:

POST /api2/partners/videos/[video-id]/languages/¶

Form Parameters:

language_code – The language code (e.g ‘en’ or ‘pt-br’) to create. title – The title for the video localized to this language - optional description – Localized description for this language - optional. is_original – Boolean indicating if this is the original language for the video. - optional - defaults to false. is_original – If set to true, will mark this language as the primary audio language for the video ( see VideoResource) - optional, defaults to false.

Information about a specific video language can be retrieved from the URL:

GET /api2/partners/videos/[video-id]/languages/[lang-identifier]/¶

Parameters:	lang-identifier – language identifier can be the language code (e.g. en) or the numeric ID returned from calls to listing languages.

Example response:

{
    "completion": "100%",
    "created": "2012-05-17T12:25:54",
    "description": "",
    "id": "8",
    "is_original": false,
    "is_translation": false,
    "language_code": "cs",
    "num_versions": 1,
    "original_language_code": "en",
    "percent_done": 0,
    "resource_uri": "/api2/partners/videos/Myn4j5OI7BxL/languages/8/",
    "site_url": "http://unisubs.example.com:8000/videos/Myn4j5OI7BxL/cs/8/",
    "subtitle_count": 11,
    "title": "\"Postcard From 1952\" - Explosions in The Sky",
    "versions": [
        {
            "author": "honza",
            "status": "published",
            "text_change": "1.0",
            "time_change": "1.0",
            "version_no": 0
        }
    ]
}

Subtitles Resource¶

Represents the subtitle set for a given video language.

Fetching subtitles for a given language:

GET /api2/partners/videos/[video-id]/languages/[lang-identifier]/subtitles/?format=srt¶

GET /api2/partners/videos/asfssd/languages/en/subtitles/?format=dfxp¶

GET /api2/partners/videos/asfssd/languages/111111/subtitles/?format=ssa¶

Query Parameters:
	format – The format to return the subtitles in. Supports all the formats the regular website does: srt, ssa, txt, dfxp, ttml. version – the numeric version number to fetch. Versions are listed in the VideoLanguageResouce request.

If no version is specified, the latest public version will be returned. For videos that are not under moderation it will be the latest one. For videos under moderation only the latest published version is returned. If no version has been accepted in review, no subtitles will be returned.

Creating new subtitles for a language:

POST /api2/partners/videos/[video-id]/languages/[lang-identifier]/subtitles/¶

POST /api2/partners/videos/asfssd/languages/en/subtitles/¶

Query Parameters:
	subtitles – The subtitles to submit sub_format – The format used to parse the subs. The same formats as for fetching subtitles are accepted. Optional - defaults to srt. title – Give a title to the new revision description – Give a description to the new revision
Form Parameters:
	is_complete – Boolean indicating if the complete subtitling set is available for this language - optional, defaults to false.

This will create a new subtitle version with the new subtitles.

Example response:

GET /api2/partners/videos/TRUFD3IyncAt/languages/en/subtitles/¶

{
    "description": "Centipede - Knife Party www.knifeparty.com\nFireworks - Pyro Spectaculars by Souza www.pyrospectaculars.com/\n\n( Sittin' On ) The Dock of the Bay - Otis Redding\nLights - Journey\nFrisco Blues - John Lee Hooker\nSan Francisco ( Be Sure to Wear Flowers in Your Hair ) - Scott McKenzie  \nI Left My Heart in San Francisco - Tony Bennett\n\nIf you didn't understand what was happening, you should probably watch it again.\nThis has been a Seventh Movement effort.",
    "note": "",
    "resource_uri": "",
    "site_url": "http://example-host/api2/partners/videos/TRUFD3IyncAt/en/1/",
    "sub_format": "srt",
    "subtitles": [
        {
            "end": 4,
            "id": 1,
            "start": 3,
            "start_of_paragraph": false,
            "text": "This is a cool bridge"
        },
        {
            "end": 5,
            "id": 2,
            "start": 4,
            "start_of_paragraph": false,
            "text": "Really cool"
        },
        {
            "end": 6,
            "id": 3,
            "start": 5,
            "start_of_paragraph": false,
            "text": "I love it"
        }
    ],
    "title": "The Golden Gate Way",
    "version_no": 0,
    "video": "The Golden Gate Way",
    "video_description": "Centipede - Knife Party www.knifeparty.com\nFireworks - Pyro Spectaculars by Souza www.pyrospectaculars.com/\n\n( Sittin' On ) The Dock of the Bay - Otis Redding\nLights - Journey\nFrisco Blues - John Lee Hooker\nSan Francisco ( Be Sure to Wear Flowers in Your Hair ) - Scott McKenzie  \nI Left My Heart in San Francisco - Tony Bennett\n\nIf you didn't understand what was happening, you should probably watch it again.\nThis has been a Seventh Movement effort.",
    "video_title": "The Golden Gate Way"
}

Language Resource¶

Represents a listing of all available languages on the Amara platform.

Listing available languages:

GET /api2/partners/languages/¶

User Resource¶

One can list and create new users through the API.

Listing users:

GET /api2/partners/users/¶

User datail:

GET /api2/partners/users/[username]/¶

Creating Users:

POST /api2/partners/users/¶

Form Parameters:

username – the username for later login. 30 chars or fewer alphanumeric chars, @, _ and - are accepted. email – A valid email address password – any number of chars, all chars allowed. first_name – Any chars, max 30 chars. Optional. last_name – Any chars, max 30 chars. Optional. create_login_token – If sent the response will also include a url that when clicked will login the recently created user. This URL expires in 2 hours

The response also includes the ‘api_key’ for that user. If clients wish to make requests on behalf of this newly created user through the api, they must hold on to this key, since it won’t be returned in the detailed view.

Example response:

{
    "avatar": "http://www.gravatar.com/avatar/947b2f9a76cd39f5c7b7c8ad3a36?s=100&d=mm",
    "biography": "The guy with a boring name.",
    "first_name": "John",
    "full_name": "John Smith",
    "homepage": "http://example.com",
    "last_name": "Smith",
    "num_videos": 8,
    "resource_uri": "/api2/partners/users/jsmith/",
    "username": "jsmith"
}

Video Url Resource¶

One can list, update, delete and add new video urls to an existing video.

Listing video urls

GET /api2/partners/videos/[video-id]/urls/¶

Video URL detail:

GET /api2/partners/videos/[video-id]/urls/[url-id]/¶

Where the url-id can be fetched from the list of urls.

Updating video-urls:

PUT /api2/partners/videos/[video-id]/urls/[url-id]/¶

Creating video-urls:

POST /api2/partners/videos/[video-id]/urls/¶

Form Parameters:

url – Any URL that works for the regular site (mp4 files, youtube, vimeo, etc) can be used. Note that the url cannot be in use by another video. primary – A boolean. If true this is the url the will be displayed first if multiple are presents. A video must have one primary URL. If you add / change the primary status of a url, all other urls for that video will have primary set to false. If this is the only url present it will always be set to true. original – If this is the first url for the video.

To delete a url:

DELETE /api2/partners/videos/[video-id]/urls/[url-id]/¶

If this is the only URL for a video, the request will fail. A video must have at least one URL.

Team Resource¶

You can list existing teams:

GET /api2/partners/teams/¶

You can view details for an existing team:

GET /api2/partners/teams/[team-slug]/¶

Creating a team:

POST /api2/partners/teams/¶

Form Parameters:
	name – (required) Name of the team slug – (required) A unique slug (used in URLs) description – is_visible – Should this team be publicly visible? membership_policy – See below for possible values video_policy – See below for possible values task_assign_policy – See below for possible values max_tasks_per_member – Maximum tasks per member task_expiration – Task expiration in days

Example payload:

{
    "name": "Full Team",
    "slug": "full-team",
    "description": "One full team",
    "is_visible": false,
    "membership_policy": "Invitation by any team member",
    "video_policy": "Admins only",
    "task_assign_policy": "Managers and admins",
    "max_tasks_per_member": 3,
    "task_expiration": 14
}

Updating a team:

PUT /api2/partners/teams/[team-slug]/¶

Deleting a team:

DELETE /api2/partners/teams/[team-slug]/¶

{
    "created": "2012-04-18T09:26:59",
    "deleted": false,
    "description": "",
    "header_html_text": "",
    "is_moderated": false,
    "is_visible": true,
    "logo": null,
    "max_tasks_per_member": null,
    "membership_policy": "Open",
    "name": "test",
    "projects_enabled": false,
    "resource_uri": "/api2/partners/teams/test/",
    "slug": "test",
    "subtitle_policy": "Anyone",
    "task_assign_policy": "Any team member",
    "task_expiration": null,
    "translate_policy": "Anyone",
    "video_policy": "Any team member",
    "workflow_enabled": false
}

Team Member Resource¶

This resource allows you to change team membership information without the target user’s input. This resource is only applicable to:

• Teams associated with the partner’s account
• Users who are already members of one of the partner’s teams

You can list existing members of a team:

GET /api2/partners/teams/[team-slug]/members/¶

Adding a new member to a team:

POST /api2/partners/teams/[team-slug]/members/¶

Updating a team member (e.g. changing their role):

PUT /api2/partners/teams/[team-slug]/members/[username]/¶

Removing a user from a team:

DELETE /api2/partners/teams/[team-slug]/members/[username]/¶

Example of adding a new user:

{
    "username": "test-user",
    "role": "manager"
}

Safe Team Member Resource¶

This resource behaves the same as the normal Team Member resource with one small difference. When you add a user to a team, we will send an invitation to the user to join the team. If the user doesn’t exist, we will create it. The standard Team Member resource simply adds the user to the team and returns.

Listing:

GET /api2/partners/teams/[team-slug]/safe-members/¶

Adding a new member to a team:

POST /api2/partners/teams/[team-slug]/safe-members/¶

Project Resource¶

List all projects for a given team:

GET /api2/partners/teams/[team-slug]/projects/¶

Project detail:

GET /api2/partners/teams/[team-slug]/projects/[project-slug]/¶

Create a new project:

POST /api2/partners/teams/[team-slug]/projects/¶

Example payload for creating a new project:

{
    "name": "Project name",
    "slug": "project-slug",
    "description": "This is an example project.",
    "guidelines": "Only post family-friendly videos."
}

Update an existing project:

PUT /api2/partners/teams/[team-slug]/projects/[project-slug]/¶

For example, to change the project’s name:

{
    "name": "Project"
}

Delete a project:

DELETE /api2/partners/teams/[team-slug]/projects/[project-slug]/¶

Task Resource¶

List all tasks for a given team:

GET /api2/partners/teams/[team-slug]/tasks/¶

Query Parameters:

assignee – Show only tasks assigned to a user identified by their username. priority – Show only tasks with a given priority type – Show only tasks of a given type video_id – Show only tasks that pertain to a given video order_by – Apply sorting to the task list. Possible values: created Creation date -created Creation date (descending) priority Priority -priority Priority (descending) type Task type (details below) -type Task type (descending) completed – Show only complete tasks completed-before – Show only tasks completed before a given date (unix timestamp) completed-after – Show only tasks completed before a given date (unix timestamp) open – Show only incomplete tasks

Task detail:

GET /api2/partners/teams/[team-slug]/tasks/[task-id]/¶

Create a new task:

POST /api2/partners/teams/[team-slug]/tasks/¶

Update an existing task:

PUT /api2/partners/teams/[team-slug]/tasks/[task-id]/¶

Delete an existing task:

DELETE /api2/partners/teams/[team-slug]/tasks/[task-id]/¶

{
    "approved": null,
    "assignee": "johnsmith",
    "language": "en",
    "priority": 1,
    "resource_uri": "/api2/partners/teams/all-star/tasks/3/",
    "type": "Subtitle",
    "video_id": "Myn4j5OI7BxL",
    "completed": "2012-07-18T14:08:07"
}

Activity resource¶

This resource is read-only.

List activity items:

GET /api2/partners/activity/¶

Query Parameters:

team – Show only items related to a given team (team slug). team-activity – If team is given, we normally return activity on the team’s videos. If you want to see activity for the team itself (members joining/leaving and team video deletions, then add team-activity=1) video – Show only items related to a given video (video id) type – Show only items with a given activity type (int, see below) language – Show only items with a given language (language code) before – A unix timestamp in seconds after – A unix timestamp in seconds

Activity types:

1. Add video
2. Change title
3. Comment
4. Add version
5. Add video URL
6. Add translation
7. Subtitle request
8. Approve version
9. Member joined
10. Reject version
11. Member left
12. Review version
13. Accept version
14. Decline version
15. Delete video

Activity item detail:

GET /api2/partners/activity/[activity-id]/¶

Example response:

{
    "type": 1,
    "comment": null,
    "created": "2012-07-12T07:02:19",
    "id": "1339",
    "language": "en",
    "new_video_title": "",
    "resource_uri": "/api2/partners/activity/1339/",
    "user": "test-user"
}

Message Resource¶

The message resource allows you to send messages to user and teams.

POST /api2/partners/message/¶

Form Parameters:
	subject – Subject of the message content – Content of the message user – Recipient’s username team – Team’s slug

You can only send the user parameter or the team parameter at once.

Application resource¶

For teams with membership by application only.

List application items:

GET /api2/partners/teams/[team-slug]/applications¶

Query Parameters:
	status – What status the application is at, possible values are ‘Denied’, ‘Approved’, ‘Pending’, ‘Member Removed’ and ‘Member Left’ before – A unix timestamp in seconds after – A unix timestamp in seconds user – The username applying for the team

Application item detail:

GET /api2/partners/teams/[team-slug]/applications/[application-id]/¶

Example response:

{
   "created": "2012-08-09T17:48:48",
   "id": "12",
   "modified": null,
   "note": "",
   "resource_uri": "/api2/partners/teams/test-team/applications/12/",
   "status": "Pending",
   "user": "youtube-anonymous"

}

To delete an Application:

DELETE /api2/partners/teams/[team-slug]/applications/[application-id]/¶

Applications can have their statuses updated:

PUT /api2/partners/teams/[team-slug]/applications/[application-id]/¶

Query Parameters:
	status – What status the application is at, possible values are ‘Denied’, ‘Approved’, ‘Pending’, ‘Member Removed’ and ‘Member Left’

Note that if an application is pending (has the status=’Pending’), the API can set it to whatever new status. Else, if the application has already been approved or denied, you won’t be able to set the new status. For cases were an approval was wrongly issues, you’d want to remove the team member. Otherwise you’d want to invite the user to the team.

User Accounts¶

• Users can link to YouTube from account section on their profile page
• A user can only link 1 YouTube account
• A YouTube account can only be linked to 1 user
• We create a video feed and import all videos for the YouTube channel.
• All subtitles for a video in that account will be synced

Team Accounts¶

• Teams can link to YouTube from their Settings -> Integrations page
• A team can link multiple YouTube accounts
• A YouTube account can only be linked to 1 team, but there is a way to share the account with other teams.
• Subtitles are normally only synced for the team’s videos
• The linked team can add other teams to the syncing list, any of those team’s videos will also be synced.
• We don’t auto-import videos for the YouTube channel.
• A YouTube account can’t be linked to both a team and a user

Example¶

MEDIA_BUNDLES = {
    "base.css": {
        "files": (
            "css/v1.scss",
            "css/bootstrap.css",
        ),
    },
    "site.js": {
        "files": (
            "js/jquery-1.4.3.js",
            "js/unisubs.site.js",
        ),
    },
}
STATIC_MEDIA_COMPRESSED = True

STATIC_MEDIA_USES_S3 = True
AWS_ACCESS_KEY_ID = 'abcdef'
AWS_SECRET_ACCESS_KEY = 'abcdef
STATIC_MEDIA_S3_BUCKET = 'bucket.name'
STATIC_MEDIA_S3_URL_BASE = '//s3.amazonaws.com/bucket.name'

MEDIA_BUNDLES¶

MEDIA_BUNDLES defines our Javascript/CSS media bundles.

The keys are the filename that we will generate. The extension of the filename controls what type of media and should either by js or css.

The values are dicts that determine how we build the bundle. They can have these properties:

files¶

list of files to bundle together (paths are relative to the media directory)

add_amara_conf(optional)¶

If True, we will prepend javascript code to the source JS files. THis will create global object called _amaraConf with these properties:

• baseURL: base URL for the amara website
• staticURL: base URL to the static media

STATIC_MEDIA_COMPRESSED¶

Set to False to disable compressing/minifying Javascript and CSS

STATIC_MEDIA_USES_S3¶

If True we Will Serve media files from amazon S3. This will change the URLs that our template tags create for links to the media bundles. STATIC_MEDIA_USES_S3 is usually True for production and False for development.

If STATIC_MEDIA_USES_S3 is enabled, the following settings are available:

• AWS_ACCESS_KEY_ID: S3 access key.
• AWS_SECRET_ACCESS_KEY: S3 secret key.
• STATIC_MEDIA_S3_BUCKET: S3 bucket to store media in.
• STATIC_MEDIA_S3_URL_BASE: Base URL for S3 media.