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. 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 would 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.

An image can also be submitted 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. The following five 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. This can be controlled by the previewHeight parameter. For more information, see Question height.

An image question can be limited 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

GpsImageDirection

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

The following example can be used to display both the latitude and longitude value in a single field, which can then be used 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

GpsImageDirectionRef

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, EXIF data cannot be extracted 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 on 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 will 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. 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. Audio files can be played repeatedly.

An audio clip can also be captured in your survey using an audio question. This captures an audio file using the default audio capture method for your device.

Audio responses are limited to two minutes in length. Survey123 records at a 22010 Hz sample rate in mono, and the audio is stored as a lossless .wav file, which means that a maximum-length audio file is about 5 MB in size. Audio quality will vary depending on your device but will typically be of an acceptable level for speech recordings.

Files

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

Survey123 allows the user to submit the following file types:

7Z, AIF, AVI, BMP, CSV, DOC, DOCX, DOT, ECW, EMF, EPS, GIF, GML, GPKG, GTAR, GZ, IMG, J2K, JP2, JPC, JPE, JPEG, JPF, JPG, JSON, M4A, MDB, MID, MOV, MP2, MP3, MP4, MPA, MPE, MPEG, MPG, MPV2, PDF, PNG, PPT, PPTX, PS, PSD, QT, RA, RAM, RAW, RMI, SID, TAR, TGZ, TIF, TIFF, TXT, VRML, WAV, WMA, WMF, WMV, WPS, XLS, XLSX, XLT, XML, and ZIP.


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