Media

Adding images and audio to your surveys can provide clear instructions and detailed references for your users. You can also include image, audio, and file questions in your surveys.

Once submitted, the responses to image, audio, and file questions are stored in the My Survey Attachments folder on your device.

By default, image, audio, and file questions accept one attachment per response. By setting their appearance to multiline in the appearance column, they can accept multiple attachments in the one response.

Images

To be included in your survey, all images must be saved in the media subfolder of your survey project.

You can add images to any question by including the exact file name of the image file (including the file extension) in the media::image column of your survey worksheet. Supported file types include BMP, GIF, JPC, JPE, JPEG, JPF, JPG, and PNG. For GIF images, animation is supported in the Survey123 web app only. The Survey123 field app also supports TIF and TIFF images.

Use a note question to display an image that is not associated with a question.

To include images for multiple choice questions, add the media::image column to your choices worksheet. Add the exact file name of the image file (including the file extension) for each choice in this column. Set the appearance of the multiple choice question to minimal to display only the images.

Note:

Survey123 is case sensitive. Ensure that all references to file names and their extensions use the same case as the actual files. For example, Tree.JPG is not the same as tree.jpg, and if referenced like this, the image does not display in your survey.

Selecting an image in a survey presents a full-screen view of the image. Return to the survey using the back button in the upper left corner.

You can also submit an image in your survey using an image question. This allows you to submit either an image saved on your device or a photo taken with your device's camera.

A photo taken in Survey123 is saved as a .jpg file, with a quality level dependent on your device's camera. You can set the image size, measured by pixels on the longest edge, on the Options tab in Survey123 Connect. This size is applied to all image questions in the survey. The following options are available:

  • 320 pixels
  • 640 pixels
  • 1280 pixels
  • 1920 pixels
  • Unrestricted (Any photo size can be attached to the survey.)

The default image size is 1280 pixels. Submitted images that were saved on the device keep their original file type, resolution, and quality.

These image sizes don't affect the image preview provided in the Survey123 field app. You can control this with the previewHeight parameter. For more information, see Question height.

You can set the maximum allowable size of an image for each individual image question in a survey. Specify max-pixels in the parameter column of the XLSForm for the question you want to limit. For example max-pixels=100 scales the image down proportionally to 100 pixels on the longest edge. If the max pixels parameter is not specified, images use the image size set in Survey123 Connect.

You can limit an image question to a particular capture method by specifying method=camera or method=browse in the body::esri:style column of the XLSForm.

Image questions also have alternate appearance types to annotate photos, draw on a canvas, or pen a signature. For more information, see Appearance.

You can also use the pulldata() function to extract standard Exchangeable Image File (EXIF) metadata tags from the response to an image question. Entering the following example into a decimal question extracts the device latitude value from an image:

pulldata("@exif", ${image}, "GpsLatitude")

Commonly used locational EXIF tags to use with pulldata() functionality are listed in the following table:

EXIF tagDescription

GpsLatitude

Latitude of the device location as a string

GpsLongitude

Longitude of the device location as a string

GpsAltitude

Altitude of the device location as a string

GpsLatitudeRef

The latitude reference (that is, N,E,S,W) of the device location as a string

GpsLongitudeRef

The longitude reference (that is, N,E,S,W) of the device location as a string

GpsDestDistance

The distance between the device and destination locations, in kilometers, as an integer

GpsImgDirection

The direction to the destination location from the device location as a string

GpsDestLatitude

The latitude of the destination location as a string

GpsDestLongitude

The longitude of the destination location as a string

GpsDestLatitudeRef

The latitude reference (that is, N,E,S,W) of the destination location as a string

GpsDestLongitudeRef

The longitude reference (that is, N,E,S,W) of the destination location as a string

You can use the following example to display both the latitude and longitude value in a single field, which you can then to populate a geopoint question:

string(pulldata("@exif", ${image}, "GpsLatitude")) + " " + string(pulldata("@exif", ${image}, "GpsLongitude"))

Other image EXIF tags that can be extracted by Survey123 are listed below. Be aware that depending on the hardware being used, not all of these tags will be available.

GpsAltitudeRef

GpsTimeStamp

GpsSatellites

GpsStatus

GpsMeasureMode

GpsDop

GpsSpeedRef

GpsSpeed

GpsTrackRef

GpsTrack

GpsImgDirectionRef

GpsMapDatum

GpsDestBearingRef

GpsDestBearing

GpsDestDistanceRef

GpsProcessingMethod

GpsAreaInformation

GpsDateStamp

GpsVersionId

GpsDifferential

GpsHPositioningError

ImageWidth

ImageLength

ImageBitsPerSample

ImageCompression

ImagePhotometricInterpretation

ImageDescription

ImageMake

ImageModel

ImageStripOffsets

ImageOrientation

ImageSamplesPerPixel

ImageRowsPerStrip

ImageStripByteCounts

ImageXResolution

ImageYResolution

ImagePlanarConfiguration

ImageResolutionUnit

ImageTransferFunction

ImageSoftware

ImageDateTime

ImageArtist

ImageWhitePoint

ImagePrimaryChromaticities

ImageYCbCrCoefficients

ImageYCbCrSubSampling

ImageYCbCrPosition

ImageReferenceBlackWhite

ImageRating

ImageRatingPercent

ImageCopyright

ImageXPTitle

ImageXPComment

ImageXPAuthor

ImageXPKeywords

ImageXPSubject

ImageLensSpecification

ImageLensModel

ImageLensMake

ImageLensSerialNumber

ExtendedSubjectDistanceRange

ExtendedExposureTime

ExtendedFNumber

ExtendedExposureProgram

ExtendedSpectralSensitivity

ExtendedISOSpeedRatings

ExtendedOecf

ExtendedExifVersion

ExtendedDateTimeOriginal

ExtendedDateTimeDigitized

ExtendedComponentsConfiguration

ExtendedCompressedBitsPerPixel

ExtendedShutterSpeedValue

ExtendedApertureValue

ExtendedBrightnessValue

ExtendedExposureBiasValue

ExtendedMaxApertureValue

ExtendedSubjectDistance

ExtendedMeteringMode

ExtendedLightSource

ExtendedFlash

ExtendedFocalLength

ExtendedSubjectArea

ExtendedMakerNote

ExtendedUserComment

ExtendedSubSecTime

ExtendedSubSecTimeOriginal

ExtendedSubSecTimeDigitized

ExtendedFlashPixVersion

ExtendedColorSpace

ExtendedPixelXDimension

ExtendedPixelYDimension

ExtendedRelatedSoundFile

ExtendedFlashEnergy

ExtendedSpatialFrequencyResponse

ExtendedFocalPlaneXResolution

ExtendedFocalPlaneYResolution

ExtendedFocalPlaneResolutionUnit

ExtendedSubjectLocation

ExtendedExposureIndex

ExtendedSensingMethod

ExtendedFileSource

ExtendedSceneType

ExtendedCfaPattern

ExtendedCustomRendered

ExtendedExposureMode

ExtendedWhiteBalance

ExtendedDigitalZoomRatio

ExtendedFocalLengthIn35mmFilm

ExtendedSceneCaptureType

ExtendedGainControl

ExtendedContrast

ExtendedSaturation

ExtendedSharpness

ExtendedDeviceSettingDescription

ExtendedImageUniqueId

To see these properties in detail, see the EXIF sample in Survey123 Connect.

Caution:

If an image question contains multiple images, you cannot extract EXIF data from the images using the pulldata("@exif") function. If you need to extract EXIF data from multiple images submitted to the same question, consider using a repeat.

Spike integration

Image questions also support integration with the Spike laser measurement solution developed by ikeGPS, which allows you to capture the measurements and location of an object from a photo. For information about how to use Spike with Survey123, see Appearance.

Spike records a number of additional custom tags by writing a JSON object to the ImageDescription EXIF tag containing nonstandard properties relating to the Spike device and the measurements it has taken. The tags are described in the following table:

Spike tagDescription

device_id

The ID of the Spike device as a string

local_accuracy

The accuracy of the Spike device as a decimal

destination_altitude

The altitude of the destination location as a rational

declination

The declination of the Spike device as a rational

pitch

The pitch of the Spike device as a rational

rotation

The rotation of the Spike device as a string

objects

A JSON array of the measured objects (area and lengths) as a string

P2P.capture_id

The ID of the two images of the point-to-point process as a string

P2P.horizontal_distance

The horizontal distance between the two points in meters

P2P.distance

The distance between the two points in meters

P2P.gradient

The gradient between the two points in degrees

P2P.vertical_distance

The vertical distance between the two points in meters

P2P.azimuth

The azimuth of the two points in degrees

To access these Spike properties, first extract the JSON object stored in the EXIF using pulldata on the objects property as follows:

pulldata("@exif", ${image}, "objects")

Once this JSON object is in another field, you can use the spike. property name path to extract a specific value from the JSON array. The following example extracts the pitch of the Spike device from the question with the array inside it:

pulldata("@json", ${spikedata}, "Spike.pitch")

The objects array also contains the areas and lengths captured by the Spike device. This array contains the measured objects in the image, including shapes and lines, as well as an alignment shape used for image transformation. The objects in the array can be extracted by referring to their position in the array, an order that corresponds to the order in which they were captured. The following example returns the first area or line in the array:

pulldata("@json", ${spikedata}, "Spike.objects[1].type")

Note:

Position 0 in the array always contains the alignment shape.

To return the amount of objects present in the array, use the length property as follows:

pulldata("@json", ${spikedata}, "Spike.objects.length")

To see examples of these tags in use, see the Spike sample survey in Survey123 Connect. For more information about Spike, visit the ikeGPS products page.

Audio

To include audio files in your survey, they must be saved in the media subfolder of your survey project.

Audio can be added to any question by including the exact file name of the audio file (including the file extension) in the media::audio column of your survey worksheet. Supported file types include MP3 and WAV. Additional audio formats are supported on certain platforms. For example, playback of M4A files is supported on iOS and macOS.

Use a note question to play an audio clip that is not associated with a question.

To include audio for multiple choice questions, add the media::audio column to your choices worksheet. Add the exact file name of the audio file (including the file extension) for each choice in this column.

When audio is included in a survey, a speaker button is active on the form. Select this button to play the audio file. You can play audio files repeatedly.

You can also record audio in your survey using an audio question. This captures an audio file using the default audio capture format for your device. Audio quality varies depending on your device but is typically of an acceptable level for speech recordings.

The default time limit for audio recordings is two minutes. This limit can be modified by specifying a max-duration value (in seconds) in the bind::esri:parameters column of your survey worksheet. For example, max-duration=30 will allow the user to record up to 30 seconds of audio.

Caution:
The maximum file size for an individual attachment submitted from the Survey123 field app is 10 MB. You will need to ensure the max-duration you set does not cause the audio file to exceed the maximum file size.

You can also submit an audio file stored on your device using a file question. For a list of supported audio file types, see Files.

Files

Media other than images and audio cannot be displayed in your survey. However, the file question type allows users to submit a range of file types, up to a maximum size of 10 MB.

By default, a file question accepts one file. Use the multiline appearance to allow attachment of multiple files to a survey.

The file question type accepts all file attachment types supported by ArcGIS Online and ArcGIS Enterprise. Supported file types are as follows:

CategoryFile types

Archive

7Z, GTAR, GZ, TAR, TGZ, ZIP

Audio

AIF, M4A, MID, MP2, MP3, MPA, RA, RAM, RMI, WAV, WMA

Data

CSV, GEODATABASE, GEOJSON, GML, GPKG*, JSON, MDB, PBF*, SD*, VRML, XML

Document

DOC, DOCX, DOT, PDF, PPT, PPTX, TXT, WPS, XLS, XLSX, XLT

Image

BMP, ECW, EMF, EPS, GIF, IMG, J2K, JP2, JPC, JPE, JPEG, JPF, JPG, PNG, PS, PSD, RAW, SID, TIF, TIFF, WMF

Video

AVI, MOV, MP4, MPE, MPEG, MPG, MPV2, QT, WMV

*Attachment type not supported in ArcGIS Enterprise.


In this topic
  1. Images
  2. Audio
  3. Files