Documentation

Media Functions

Overview

Read reusable data and attachments from named survey materials. Use row helpers for typed fields, such as product IDs or ZIP codes. Use the image or video helpers to retrieve files to display to respondents. See Including media in your survey for upload and security options.

Reading rows and column values

The first argument to s.get_material() and s.get_materials() is a case-insensitive material name or its ID. Pass exact values as keyword filters, and use column to return only one field per matching row.

Code
product = s.get_material("Products", code="P001") name = s.get_material("Products", code="P001", column="name") products = s.get_materials("Products", brand="Alder") names = s.get_materials("Products", brand="Alder", column="name")

get_material() returns one row dictionary or one column value. A lookup that matches zero or multiple rows raises a survey validation error. get_materials() returns a list in stored row order. A filtered lookup with no matches also raises a validation error. Reading an empty material without filters returns an empty list.

For a respondent-entered value that may be missing from the table, see Import a ZIP code lookup table.

Image and video attachments

Pass the material name or ID to get_image, get_images, get_video or get_videos. Use keyword arguments to filter by exact metadata values. The singular helpers require exactly one matching attachment. The plural helpers return all matches and raise a ValueError when there are none.

get_image(material, **filters)

Code
image = s.get_image("Creatives", file_name="advert.png") s.select_question( "What do you think of this ad?", options=["Like", "Dislike"], image=image, )

Image crops

Use crop_selection to show an area selected in an image-highlighter answer. The metadata filters must identify exactly one source image in the material.

Code
image = s.get_image("Creatives", file_name="advert.png") answer = s.image_highlighter_question("Highlight areas you like.", image=image) for index, selection in enumerate(answer.rectangles): cropped = s.get_image("Creatives", file_name=image.file_name, crop_selection=selection) s.text_question( "Why did you choose this area?", image=cropped, id="area_follow_up_" + str(index + 1), )

A crop retains the source filename, metadata and security mode. Use the receiving question's image_size to control how large the crop appears. For the full image, omit crop_selection or set it to None.

Crops can be used in ordinary question images and image options. Image-highlighter questions require an uncropped source. See Image Highlighter Question for configuration and response geometry.

get_video(material, **filters)

Returns the single video matching the provided metadata filters. As with get_image, the filters must identify exactly one video: more than one match stops the survey with The media collection contains 2 videos with the given parameters, expected no more than 1., and no match stops it with Cannot find media that meets the condition .... Use get_videos when you want to work with every match.

Code
ford_video = s.get_video("Creatives", file_name="ford.mp4") s.play_video(video=ford_video)

get_video_thumbnail(video, offset_seconds)

Returns a reusable image of a video at the whole second containing the requested timestamp. Use it as a question image, with show_image, or in image options.

Code
video = s.get_video("Creatives", file_name="advert.mp4") frame = s.get_video_thumbnail(video, offset_seconds=12.8) s.text_question("What do you remember about this moment?", image=frame)

This example requests second 12. Zero is valid for the start of the video. Offsets must be finite, non-negative numbers; fractional values are truncated to whole seconds. Boolean offsets and non-video sources are rejected.

The image keeps the video's metadata. Its file_name and offset_seconds tags identify the source video and requested second for reporting. Missing or processing frames display a temporary placeholder.

Use the same get_video_thumbnail(video, offset_seconds) call for Secure and Non-secure videos; no extra security flag is needed. A Secure frame inherits protected, watermarked viewing from the source video. Original-video downloads and review-overlay MP4s remain restricted to eligible Non-secure media.

Test the survey through the video and its follow-up question. Playback can be ready while a requested frame is still processing; a temporary placeholder means the frame is not yet available. Check that the intended frame appears before fielding.

You can pass a dial reaction section's start_seconds directly to this method. See the API reference for the complete contract.

get_images(material, **filters)

Returns a list of every image matching the provided metadata filters. If no image matches, this raises a ValueError (Cannot find media that meets the condition ...) rather than returning an empty list, so a filter that matches nothing will stop the survey rather than silently skipping the loop.

Code
for image in s.get_images("Creatives", brand="Ford"): s.select_question("What do you think of this Ford car?", options=["Like", "Dislike"], image=image)

get_videos(material, **filters)

Returns a list of every video matching the provided metadata filters. As with get_images, a filter that matches no videos raises Cannot find media that meets the condition ... rather than returning an empty list.

Code
for video in s.get_videos("Creatives", brand="Ford"): s.play_video(video=video)

Ad Exposure Tagging

For campaign effectiveness studies, exposure data (for example, ad server logs) can be pre-loaded into the MX8 Labs Research Platform and matched to respondents using the identifiers supplied with those records. Two functions make that exposure data available in survey code.

tag_exposed_materials

Tag rows in a named material using the current respondent's preloaded exposure records. The platform matches the values in field_name to the exposure dimension for the configured source. The dimension defaults to brand. Use number_allowed_unknown_values when the study permits some exposure values outside the allow-list.

Code
s.tag_exposed_materials("Creatives", source="campaign-123", field_name="brand") for image in s.get_images("Creatives"): s.select_question( "What do you think of this ad?", options=["Like", "Dislike"], image=image, tags=s.tag(exposed=image.exposed), )

Each row receives a Boolean exposed tag. Exposed rows also receive frequency and, when available, days_since_exposure. You can read these tags from rows or attachments during the current respondent's survey. The stored material stays unchanged.

get_exposures(source, id=None)

Returns reportable exposure records for the current respondent. Each record carries all its linked dimensions as attributes, plus frequency, exposure_source, and days_since_exposure when available. This lets survey logic match a campaign and creative on the same exposure record.

ParameterTypeRequiredDescription
sourcestryesNon-empty name of the configured exposure source.
idstrnoReporting ID for the exposure records.
Code
exposures = s.get_exposures(source="campaign-123", id="ad-exposures") saw_target_creative = any( exposure.campaign == "campaign-a" and exposure.creative == "creative-b" for exposure in exposures )

Use the dimensions configured on your source. For a full survey example and simulation guidance, see Using exposure data in your survey.

The older get_exposed_values(source, exposed_dimension, ...) method is deprecated. It returns values for a single dimension; use get_exposures for new code that needs linked dimensions.

DRM and Security

Secure or Non-secure is chosen for each image or video before upload. The mode is fixed for that asset and is preserved through metadata edits, replacements, retries and survey copies. To change modes, upload a new asset under a different filename. See Uploading your media.

Secure media uses protected delivery. Video-specific browser controls apply while a secure video is shown:

ProtectionWhat it does
Anti-tampering video overlayA transparent overlay sits on top of every video and detects attempts to modify, replace, or scrape the player. Any tampering pauses playback and invalidates the session.
Pause-on-backgroundPlayback automatically pauses the moment the tab, window, or app loses focus. Respondents cannot leave a video running in the background while switching to a screen-capture tool.
Right-click preventionThe standard context menu is disabled on media elements, so respondents cannot save the underlying asset directly.
Keystroke blockingCommon screen-capture and developer-tool keyboard shortcuts are intercepted while media is on screen.
DRMSecure videos use DRM playback to restrict unauthorized access and copying. Non-secure videos use standard playback.

Secure images, video posters and timestamped frames use protected, watermarked delivery; secure videos use short-lived playback access. Ordinary original-file downloads and review-overlay MP4s are available only for eligible Non-secure assets and users with export permission.

Image-highlighter reports use source originals, including Secure images, for analysis, report display and PNG/ZIP composition. Those reports have their own access and download controls.

Choose Secure before uploading confidential or unreleased stimuli that need protected viewing. Choose Non-secure when the study requires original downloads or review-overlay exports.

Notes

  • You can chain filters using multiple keyword arguments (e.g. brand="Ford", campaign="Summer"); an item must match every filter to be returned
  • Filtering on a metadata column that does not exist — for example, a typo in a keyword argument name — raises an AttributeError rather than returning no matches, so keyword argument names must match your media's metadata columns exactly
  • These tools allow dynamic, personalized question flows based on metadata
  • Media metadata is automatically included in reporting for grouped analysis
  • All media must be uploaded via the MX8 Labs Research Platform dashboard and tied to the current survey project
  • See Secure Video Player for the video-specific instrument that pairs with these protections