Article

Guidelines for Using Images, Videos, and Audio Files

Get the requirements and recommendations for using images and other media in your article.

Overview

You can use images, videos, and audio files in a variety of ways throughout your article. For example, an image can be used as a logo, as cover art, as a background, or as a placeholder for a video while it’s not playing. Video files can be used within an article to enhance the user’s experience, or as the thumbnail that represents the article in the user’s News feed. You can use either the audio or the music component to include audio files in your article.

URL Guidelines

If the URLs in your video, image, or audio file contain special characters, such as spaces or parentheses, be sure to use percent encoding to ensure that your link works correctly. For example, any spaces in a URL should be encoded as %20.

If your URL has links nested within other special characters or formats, such as Markdown, use layered encoding. Percent encode the URL first and then use special character escaping.

This example shows layered encoding.

{
  "role": "body",
  "format": "markdown",
  "text": "\\([Library of Congress](http://memory.loc.gov/cgi-bin/query/h?ammem/rbpebib:@field%28NUMBER+@band%28rbpe%2B1310110b%29%29)\\)”
}

For URL guidelines specific to image, video, and audio files, see the relevant sections below.

Image Guidelines

To include an image in your article, you use a URL to specify the location of the image file. Make sure to encode any special characters in the URL (such as spaces or parentheses). See URL Guidelines.

You can specify an image as a property in any of the following contexts.

Component or other context

Property

Audio

imageURL

ArticleThumbnail

URL

DataTable

imageURL for the value of a record when dataDescriptor has image as its dataType.

Figure

URL

Image

URL

Logo

URL

Music

imageURL (Optional)

Photo

URL

Portrait

URL

Video

stillURL (Optional)

ImageFill

URL

RepeatableImageFill

URL

VideoFill

stillURL

GalleryItem

URL

Gallery

items

Mosaic

items

Metadata

thumbnailURL

When you choose images to include in your article, be sure to follow these specifications and recommendations.

Begin image URLs with a supported prefix. Apple News Format supports three prefixes for image URLs: http://, https://, and bundle://. If the image URL begins with bundle://, the referenced image file must be in the same directory as the JSON document.

Use any of the supported image types: JPEG (.jpg or .jpeg extension), PNG, or GIF.

Use a high-resolution image so it can be smoothly scaled down. The image is automatically scaled to the correct size.

Use images no larger than 20 MB. Neither height nor width should exceed 6,000 pixels.

Use the following suggested minimum image widths for components. Because minimum image size is determined by the size of the component, there is no universal minimum size for images. For example, full width for an article designed for 1,024-point width and 120-point margins is different from full width for an article designed with different specifications.

  • Photo, Portrait, Gallery, and Mosaic components: 640 pixels minimum width.

  • Logo component: 300 pixels minimum width.

  • Figure component: 1,080 pixels minimum width.

Use the Display P3 color profile. This color profile creates images that are well suited both for Apple devices that support a wide color gamut and those that don’t.

Representing Your Article with a Thumbnail Image in Feeds

For each article you publish, Apple News Format automatically creates an article tile. An article tile provides information about the article. It uses information from the article’s Metadata object and appears in the topic and channel feeds and in the user’s For You feed. You use a thumbnailURL in your article metadata to specify the image you want to use in the article tile.

When you choose images for your thumbnails, be sure to follow these specifications and recommendations.

Use a high-resolution image so it can be smoothly scaled down. The image is automatically scaled to the correct size.

Use any of the supported image types: JPEG (.jpg or .jpeg extension), PNG, or GIF. (If you specify a GIF to use as a thumbnail, it is converted to a JPEG.)

Observe the minimum image size. The minimum size for a thumbnail image is 300 pixels by 300 pixels.

Ensure that the image aspect ratio (width ÷ height) is between 0.5 and 3.0.

To improve the loading time of an article, use the same image file for the thumbnail image that you use in the article. If you use the same images in both places and the image appears on the first screen of the article, the image moves with an animated effect from the feed to the article.

Video Guidelines

Use a video component in your article that can be played using an AVPlayer. Specify the location of the video file with the URL property using these guidelines.

Begin your video URLs with http:// or https:// (preferred).

Make sure your video is in one of the supported HLS formats—preferably the M3U playlist format. For more information about HLS, see iOS developer documentation about HTTP Live Streaming, especially the following sections of HTTP Live Streaming Overview:

Representing Your Article with Video in Feeds

You can use a video in your article tile by adding the videoURL property to the Metadata object. You can also specify an image to use as the thumbnail image (thumbnailURL) when the video has not yet played. A glyph appears on the thumbnail image, allowing users to play the video in the For You, topic, and channel feeds.

When you choose an image for your thumbnail, be sure to follow these specifications and recommendations.

Begin your video URLs with either the https:// (preferred) or http:// format.

Use the same URL for videoURL as for one of the video components in your article.

To ensure that playback continues seamlessly from a video playing in the feed to the same video when the article opens, make sure that the thumbnailURL property in metadata uses the same image file as the video component’s stillURL.

Make sure your video is in one of the supported HTTP Live Streaming (HLS) formats—preferably the M3U playlist format.

Using an Image with Your Video File

If you want to include a cover or other image to be shown when the video has not yet been played, use the stillURL property of Video to specify the location of the image. Make sure any special characters in the image URL are properly encoded as described in URL Guidelines.

Audio Guidelines

Use the audio or music components to include an audio file in your article. Specify the location of the audio file with the URL property, using these guidelines.

Begin your audio URLs with https:// (preferred) or http://.

Use a supported format. The audio component supports all AVPlayer audio formats, including:

  • MP3

  • AAC

  • ALAC

  • HE-AAC

Using an Image with Your Audio File

If you want to include album cover art or another image with your audio file, use the imageURL property of the audio component to specify the location of the image. Make sure any special characters in the image URL are properly encoded as described in URL Guidelines.

See Also

Component Measurements and Media Guidelines

Specifying Measurements for Components

Specify the units of measure to use for margins, minimum heights, and other dimensions.

type SupportedUnits

The units of measurement supported by Apple News Format.