Contribute to Docs Contribute to Docs

Media Files

By default Piranha allows the following files to be uploaded into the Media library.

  • .gif, .jpg, .jpeg, .jfif, .png & .webp images
  • .mp3 & .wav audio files
  • .mp4 videos
  • .pdf documents

The reason for such a restrictive upload policy is simply that these are the types of files that are supported on most devices, included the different mobile devices out there.

Referencing Media

Media files can be easily referenced in your content types by using any of the available media fields. The following example shows a Page Type referencing an image, a video, and a list of media objects of any type.

using System.Collections.Generic;
using Piranha.Models;
using Piranha.Extend.Fields;

public class MediaPage : Page<MediaPage>
    public ImageField Image { get; set; }

    public VideoField Video { get; set; }

    public IList<MediaField> Assets { get; set; }

Processing Images

If you want to crop or resize images you will need to have an image processor registered in your application. For more information on this and the different processing operations available, please refer to Image Processing in the section Architecture.

Querying Media

All methods for accessing media files can be found in the current IApi in the MediaRepository. This following code would get all available media assets in the root folder in the media library.

using System.Collections.Generic;
using System.Threading.Tasks;
using Piranha;
using Piranha.Media;

public Task<IList<Media>> GetMediaInRootFolder(IApi api)
    return api.Media.GetAllAsync();

Uploading Media

Media files can be uploaded easily from a Stream or a Byte Array by using the current IApi.

Upload media from a stream

using System.IO;
using System.Threading.Tasks;
using Piranha.Models;

using (var stream = File.OpenRead("myimage.png"))
    await api.Media.SaveAsync(new StreamMediaContent
        Filename = "myimage.png",
        Data = stream

Uploading media from a byte array

using System.Threading.Tasks;
using Piranha.Models;

await api.Media.SaveAsync(new BinaryMediaContent
    Filename = "myimage.png",
    Data = myByteArray

Media Meta Data

Media assets have the following meta-data available that you can edit both from code or from the manager interface.


media.Title = "The important document";

Optional title that can be used for rendering the media assets without their filename.


media.AltText = "Nice looking image";

Optional alt text that can be used when rendering images.


media.Description = "This is an image of me backpacking.";

Optional description that can be used when rendering the media asset.

Adding Media Types

If you need to handle more media types in your application you can easily register them in your application startup after the Piranha.App has been initialized. The following code will for example allow .gif images.

Piranha.App.MediaTypes.Images.Add(".bmp", "image/bmp");

It's very import to classify the media types your add correctly in terms of what type it is (document, image or video). This is so that Piranha knows what to do with the file.

Disabling Image Processing

When adding new image types it's important to verify that the currently installed Image Processor can handle the image type. For example, the ImageSharp processor can't handle .svg images. When adding image types you can bypass the processor which means that the original image will always be returned.

Piranha.App.MediaTypes.Images.Add(".svg", "image/svg+xml", false);

Adding Meta Data Properties

You can also add custom meta data fields to your media assets, for example an External Id if you're importing media from elsewhere. This is done in Startup.cs and applies to all media assets in the application.


These custom properties are available when editing the media asset both from the manager interface or from code.

media.Properties["ExternalId"] = "23";