Preparing Image, Video, Audio, Music, and ARKit Assets

Images, videos, audio, music, and ARKit files serve a variety of purposes in your article. For example:

• Use an image as a logo, as a background, or as a placeholder for video while it's not playing.

• Use video files in an article to enhance the user's experience, or as the thumbnail that represents the article in the user's News feed.

• Use the audio or music component to include audio files in the article.

When you use such files, you provide the encoded URL in an Apple News Format property, and the asset based on the specifications given here. Which URL property you use depends on whether the file is an image, video, audio, music, or ARKit file, and how you use it.

To include an asset in your article, provide a well-formatted and -encoded URL to specify the location of the asset file. To learn which URL property to use, see Audio, ArticleThumbnail, DataTable, Figure, Image, Logo, Music, Photo, Portrait, Video, ImageFill, RepeatableImageFill, VideoFill, GalleryItem, Mosaic, Metadata, or ARKit.

Include the URL's prefix. Apple News Format supports the following prefixes for URLs:

• http://

• https://

• bundle://—If you are using the URL property, the bundle:// prefix is not supported for Video and Audio objects. For Audio, Music, Video, and VideoFill objects use bundle:// for imageURL and stillURL. When a URL begins with bundle://, the referenced file must be in the same directory as the JSON document.

Use layered encoding for links nested within special characters or formats. This example shows layered encoding for markdown format.

{
  "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)\\)”
}

Follow the steps below to include an image in your article.

Use a supported image type. JPEG (.jpg or .jpeg extension), PNG, and GIF are all supported, but JPEG with high-quality compression setting is preferred. Use PNG only if you need transparency.

Choose a high-resolution image. The image is automatically scaled to the correct size, and high-resolution images scale smoothly.

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 for those that donʼt.

Check the size of the image. Do not exceed 20 MB for the image file size. Neither the height nor the width should exceed 6,000 pixels. Avoid using images that are tall and narrow because they do not render well across all devices.

Use the recommended minimum image width. There is no universal minimum size for images; the minimum is determined by the size of the component. 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.

The recommended minimum widths are as follows:

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

• Logo component: 300 pixels.

• Figure component: 1,080 pixels.

For images that span the full width of the document or the device, the recommended widths are as follows:

• Full width of the document. At least as wide as the document, as specified in layout.width. See Layout.

• Full width of the device. At least 1,366 pixels, to support larger devices.

Use only RGB color mode for images. RGB—Red, Green, and Blue—is the only color mode that is compatible with Apple News. Do not use CMYK—Cyan, Magenta, Yellow, and Key (black).

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. Use thumbnailURL in your article metadata to specify the image you want to use in the article tile.

Use a supported image type. JPEG (.jpg or .jpeg extension), PNG, and GIF are all supported, but JPEG with high-quality compression setting is preferred. Use PNG only if you need transparency.

Choose a high-resolution image. The image is automatically scaled to the correct size, and high-resolution images scale smoothly.

Check the size of the image. The minimum size of a thumbnail image is 300 pixels by 300 pixels.

Verify the image aspect ratio. The aspect ratio is the proportion of an image's width to its height and should be between 0.5 and 3.0.

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 for those that donʼt.

Use an image from the article as the thumbnail image. If you use the same image in both places and it appears on the first screen of the article, it moves with an animated effect from the feed to the article. Using the same image improves the loading time of the article.

Follow the steps below to include a Video or a VideoFill in your article.

Include a still image. Use the stillURL property to specify the URL of the image file to use as a still image when the video is not playing. This property is required for VideoFill and optional for Video. To avoid letterboxing, make the aspect ratio of the stillURL image file match that of the video.

Use the URL property to specify the location of the video file. The video URL should begin with https:// (preferred) or http://.

Use supported HLS formats. M3U playlist is the preferred format. For more information about HLS, see the iOS developer documentation about HTTP Live Streaming.

To add a video to your article, specify 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.

Provide a URL. Apple News Format supports the following prefixes for video URLs:

• https:// (preferred)

• http://

Use the same video URL for the Metadata videoURL property. Provide the same videoURL property value to the Metadata object and the Video component in the article.

Use the same image for the Metadata thumbnailURL property. Provide the same thumbnailURL property value to the Metadata object and the Video component’s stillURL. Using the same image ensures that playback continues seamlessly from a video playing in the feed to the same video that plays when the article opens.

Use supported HLS formats. M3U playlist is the preferred format. For more information about HLS, see HTTP Live Streaming.

Configure the Audio or Music component to include an audio file in your article.

Provide a URL. Apple News Format supports the following prefixes for audio URLs:

• https:// (preferred)

• http://

Use the imageURL property. This property adds an audio or music file to the article.

Use a supported AVPlayer audio format. The supported formats are MP3, AAC, ALAC, and HE-AAC.