Create basic entity type definition

I think for the first two, even we don't have an API yes, it should be planned (columns etc.).

Sorry for droping so late in the discussion, but is there a summary of the reasons (and the discussions about them) why the File entity is not usable as basic entity for media handling?

@mongolito404 you can find a report of the discussions at https://groups.drupal.org/node/327768 and on the dsicussion report in https://drupal.org/node/2099481

I'll crossposts some interesting remarks from the groups-discussion.

If File entity is extended to be a Media entity, then from the OOP point of view, it is no longer File entity. There were some discussions in the past:

https://drupal.org/node/1874994#comment-6917816
https://drupal.org/node/1602218

A media is atomic: one media is one tweet, not two. However, a node, or any entity can reference to multiple media. So a media collection (read, "gallery") can reference to multiple media, each can be a tweet.

https://groups.drupal.org/node/327768#comment-972868

Exactly the problem with with current media solutions. They are trying to provide users with fixed tools, when site builders want to solve special requirements.

As an example, let's say I want a gallery which:
- Has a title
- Description
- Location (name/tag/address/?)
- Thumbnail image
- Author
- Video field
- 0-n images

So it's definitely not a simple view.

Image (media_entity) might have an uploaded file, or linked image. It can also have a separate title and caption fields. Geo-coordinates. Date. Exposure.
Videos might be local also, or linked from Youtube, Vimeo and the like. If they don't need any extra fields, they can be just simple fields of the gallery content type. But the media_entity works like entity_reference with some additional field formatters and display mode support for other modules to extend.
Naturally this concept needs iterations, because it was the work of one day during the contribution sprints.

https://groups.drupal.org/node/327768#comment-969313

The URI of a File entity can be changed. And the URI of a file entity does not need to be a local file. AFAIK, the URI of a file must be supported by a PHP Stream Wrapper. So, if one was to provide Stream Wrappers for Amazon S3, YouTube and Vimeo, a File entity could be created firt with a local file URI, then update to use a file stored on S3, then a YouTube stored video and finally a Vimeo stored video.

https://groups.drupal.org/node/327768#comment-973863

My two cents from an evaluation I made a couple months ago to choose between Scald and Asset on a client site:

One critical piece of the architecture that should be retained is the separation between the media type (e.g "video") and the various providers for this media type (local file, youtube, vimeo...)

Each media type needs to be able to support an arbitrary number of "provider" plugins - and the mechanism that supports this pluggability needs to be provided by the "core media system", rather than be (if at all) reimplemented by each media type separately (which is IMO what scald got right and asset got wrong)

https://groups.drupal.org/node/327768#comment-969238

I was not in Prague and did not participate to the discussion, so this may have already been discussed.

If I understand correctly, the idea of the Media enttiy type is to allow different ressources providers to be implemented (local files, youtube vidéos, etc.). So at the lower level, the field types are ressource providers, developpers wanting to add support for new providers use the Field API. And at the Media API consumer level, the Media entities provide the known Entity APIs to manage the media and their meta-data.

But Drupal already offer two layers: Files and PHP Streams. At the lower level, a File in Drupal reference an PHP Streams using a URI. And a PHP Stream is just a seekable, readable and optionnaly writable stream of bytes. So at the lower level, ressources providers are Stream Wrappers. And for a Media API consumer level, the File entities provide the known Entity APIs to manage the media and their meta-data.

For developpers, using PHP Streams may be harder than working with the Field APIs. But it avoid adding another layer and provide a clear, basic and simple definition of what a ressource is (and is not). Also, it provide a standard interface to the ressources, allowing, for instance, generic meta-data extraction from media ressources (eg. extracting EXIF from a Stream). Something that the Media entity can not achieve without adding yet another (custom) layers.

Have the PHP Streams and Stream Wrappers considered at the Prague Media meetings ? Except the, maybe, harder API and new concepts to learn for developpers, what are the reasons for not using them?

Note: If I'm not mistaken, the current Media 7.x-2.x module implements, or aim to implement, (remote) ressources providers (such as YouTube of Flickr) as PHP Stream Wrapper.

But in Drupal 8, files are (classed) entities so there is no need to overtake the file_managed table?

Conceptually, yes the "File Entity - PHP Stream" relation is like the "Media entity - Media Ressource" relation. And that's why I'm questionning the need to introduce the "Media entity" and "Media Ressource".

Yes, using PHP Stream introduce the assumption that a media ressource is a stream of bytes. But that does not seem unreasonable. It also clearly define where the meta-data of a media is stored (ie. the File entities). Which again does not seems to be a unreasonable assumption. And if a media actually contains its meta-data, extractors could be added as plugins. And because the extractors deal with PHP Stream, they are naturally decoupled from the media ressource provider. An ID3 meta-data extractor does not need to known anything about the Stream Wrapper.

Some media ressources use cases:

A Tweet could be a media. The Stream Wrapper provide the JSON representation of the tweet as a byte-stream. A Tweet meta-data extractor can extract the author, time, etc. information fron the JSON. While a Tweet formatter could format the Tweet's JSON.
A image hosted on Flickr can be provided through a generic HTTP Stream Wrapper. Meta data could be provided through a generic EXIF extractor or by a generic oEmbed extractor (able to detect that that a HTTP URL to a Flickr file can be resolved by the Flickr oEmbed end point).
A video hosted on a YouTube could be provided through a dedicated PHP Stream Wrapper which does not provide the byte stream for the video itself. Instead it provide a JSON representation of the video, containing it meta-data. Dedciateds YoutTube formatter and extractor are used.
Or another PHP Stream Wrapper could expose a YouTune video as the stream to the actual video. Generic video meta-date extractor and formatter can then be used. Without preventing specialized extractor and formatter to be used too (because they see the YouTube URL and can act accordingly).
On the WYSIWYG side, media embedding could be based on oEmbed. decoupling the plugin from both Drupal and the way media are implemented in Drupal. Off course, the Media would expose a oEmbed endpoit for all the managed media. For remote media ressource hosted on a platform which itself expose an oEmbed endpoint (Flickr, YouTube), this endpoint could simply act a proxy (enventually decorating the results with additional data) While for a media ressource from a non-oEmbed provider (local files, S3, etc.), the Drupal side would use its formatters and extractors to provide the oEmbed data.

https://groups.drupal.org/node/327768#comment-972788
https://groups.drupal.org/node/327768#comment-973783

From https://drupal.org/node/2101855

• We don't want that every managed file is a Media Atom entity.
• Multple Media Atom entities (with different title, caption...) can reference to the same File entity (or any resource).
• One Media Atom entity can have multiple revisions, each reference to a different File entity (or any resource).
• Media Atom may not always have a filesize or mimetype like a traditional file. A "transcoded" Media Atom may have. Each transcoded Media Atom may be a file.

IMHO, these three points shows a very different approach. On one side (where I stand), we have media as files (aka. mimetyped streams of bytes), and on another side (Scald and Media Entity) media are seen as structured contents managed in a library.

My issue with that second approach is that it draw a line between the traditional Drupal content (aka. nodes) and media content (aka. Media atoms or Media entities). And it does what Drupal has not been doing for its content, provide a rich and complex UI to manage it as a library. Managing media contents through a rich a complex UI is super nice and much needed. My fear here is that the Media module/initiative will turn to an attempt to build a great fit-all UI. But, just like any other content, there is no fit-all solution. So it will eventually fail to build one (that does not mean it will not be successful in providing a awesome solution for a lot of users).

There is a place and a need for a Scald-like solution in Drupal, and it could be part of the Media module/initiative. But. IMHO, it should be build on a simpler solution that deal with file meta-data (extraction and storage), file rendering (formatters and view modes), files embedding (Drupal as an oEmbed endpoint and an oEmbed WYSIWYG integration) and files management. This simpler solution should be at the core of the Media module/initiative, and the Scald-like part should be build on it and encourage/force its usage for base media types (anything that is, or is consumed as, a stream of bytes). This simpler solution is what, I think, the current 7.x-2.x is (or is trying to be). And the current proposition seems like it will be throw away in favor of (re)building Scald using more drupalisms from 7 and 8 but without providing any features of the simpler file oriented solution. And developers or users who don't need the super rich and complex media library management layers and UI will get nothing unless they accept the unnecessary complexity of several levels of abstraction and UI they actually don't need.

Thanks for the repsonse, and for chiming in the discussion.

The aim of media_entity is absolutely not to provide a complex_ui / fit all solution. but to provide the base_entity from where all kinds of simple and complex ui's (Widget / formatters / plugins / providers) can be built.
The problem with the approuch for media as file, is that for some media-elements we need to build around, to make it fit. While actualy media as a file, is a special case. That was why we think the need for a global entity is needed, with file's as a specific subcase. Drupal 8 luckily offers the possibility to swap those things, without it being a hack.

For the further development, we're explicitly trying to aim to make use of ' file meta-data (extraction and storage), file rendering (formatters and view modes), files embedding (Drupal as an oEmbed endpoint and an oEmbed WYSIWYG integration) and files management' and certainly not reinventing the wheel.

I hope i make the point of the approach a bit more clear, i'm not trying to close this discussion, for more technical discussion i hope slashrm and jcsio can chime in.

The media entity is an unnecessary layer when only the media as files solution is enough. And the only reason the media entity is needed is to be able to build a complex and rich experience for users in need of a media as structured content managed as a library solution.

I see no reasons not to build the base features (rendering, embedding, meta-data) on the File entity. A Media entity (or actually, more a Media Library Item entity type) can then be provided as a additional layer needed to build a media as structured content managed as a library solution.

A multi-layers architecture more like this

• Drupal core provides Stream Wrappers for local files (public:// and private://), while third-party module provide wrapper for other sources such as YouTube or Flickr.
• The Media module enhance the File entity already provided by Drupal core. And provide the API and UI to handle files rendering, meta-data extraction, embedding and management.
• The Media Entity module provide the additional API and UI to manage a media library. A Media entity can use anything as resource (a File entity, a tweet, a node, etc.). The Media Entity module provide a common API and UI to embed and manage the resources, re-using the API and UI components of the resources types providers.

Note: With this approach, I would suggest requiring Media resources to be entities. Because entities have fields and view mode, it means that for a Media entity, the media as structured content solution could always rely on its resources to be structured data (entities with fields) and different rendering (views mode) implemented through a well known (an existing) interface.

If the Media entity based solution is build so a Media entity inherit (and optionally override) its resource meta-data as its data (eg. the title of a Media entity is the title of its File entity unless overrided by the end-user), and re-use its resource's renderers (ie. In view mode X a Media entity whose resource is a File entity is rendered using view mode Y of that File entity) what would prevent a site build with the File entity solution to be easily upgraded to the Media entity one? Once the Media entity solution is configured a batch job could create the Media entities for the existing File entities (this could be optional and configurable using some sort of files filter).

The base file entity based solution could provide a oEmbed based solution for both embedding and WYSIWYG integration. On the server side, an oEmbed endpoint expose the File entities as oEmbed resources. On the client side, an oEmbed plugin provide a first widget to browse for resources (ie. a simple but clean file browser) and a second widget to configure the display of the selected oEmbed resource (ie. maxwidth, maxheight and likely additional custom parameters). The oEmbed endpoint and the widgets should be extendable and/or overridable, so the Media entity based solution could enhance the UX by providing a media browser as oEmbed resource browser, adding additional parameters for the embedding configuration widget and replacing the File-entity based oEmbed endpoint with a Media entity based one. Providing both endpoints use the same URL for a File entity and one of the Media entity using this file, there is not need to migrate existing embedding data.

But if you start with a Media entity solution, the developers will always have to deal with the additional layers, and the end-users will always be have a UX designed for features they don't need. So for them, there wont be any simple solution build on Media entity. Eventually, these end-users will find developers to provide them a simple media solution. But it will be built outside the Media initiative, likely not-reusing components from the Media initiative (because these components are eithernot known or not designed to support their simpler needs). And we will end up with the same situation as we are now (ie. good but incompatible implementations of the two different approaches unable to re-use each others components).

Half-baked File entity based solution (like oEmbed integration) is broken and should be fixed. Stream wrapper, which is just a File URI, has nothing to do with File Entity and should not require File Entity, it should work with any entity. We can also make a mocked File entity (not stored in the db) if a module really requires a File entity, but I recommend against it. Again, File URI is enough.

And I believe Media entity is simply enough to use. We are in D8 after all.

@jcisio

1. What exactly is broken in the suggested File entity based oEmbed WYSIWYG integration? And how exactly is a Media entity type required to fix it?
2. Yes anything build on top of File URI and Stream Wrappers has nothing to do with File entities, could work without File entities, and could even work outside of Drupal. But since a File entity has an URI, anything build on top of File URI and Stream Wrappers and outside of Drupal is re-usable as component in a File entity based solution. Nothing is lost or gained on that front when File entities are used.
3. No a File URI is not enough, a File URI does not provide any meta-data about the file it identifiies (mime-type, size, creation date, etc.). According to the discussions, a Media entity is not the proper place for a file metadata since a Media entity may use several files.
4. The fact that the introduction of a Media entity type is questionned by me and others is a clear indication that what you believe is not everybody's opinion. Believing that we are wrong is not a good enough reason to ignore us or to disregard our opinion.
5. I believe Media entity is complexe enough to not be used by some end-user an developpers. We are in D8 after all, File entites are there. The Drupal file API is based on File entities. So a solution build without File entities will have to provide it own API aside or on top of the Drupal file API. That's why I'm suggesting a solution where Media entities are used on top of the File entities, where File entities are used wherever they are enough and where Media entities are used where File entities are not enough. A proper File entity based WYSIWYG integration could be enough for a lot of users, there is no reason to burden them with Media entities.

- Fact: most (80%-90%) people at the Prague Media sprint agreed on Media Entity.

- Fact: in Drupal 4, 5 and 6, there was node_images module. Scald invented "atom" (aka entity) to not use Node in Drupal 6. It turned out in D7 that Entity is good and not everything is a node.

- Fact: in Drupal 6 Media (sort of) used File. In Drupal 7 it still uses File. Commerce products are not File. Nodes are not File. Comments are not File. But they are all can be Media.

- Bonus fact: All File related data (mime-type, size, creation date, etc.) can be determined using file_get_mimetype(), filesize()... Drupal does it. No File Entity.

I'd say that, Media based on File Entity is like create a new node type instead of make a new Entity type and define a bundle.

slashrsm also said, and I agree, that if you make the browser layer based on File Entity, it is not extensible, because you will have to swap out the File Entity to use Media Entity. So let's use Media Entity at the beginning.

I agree with the Media entity so that would place me in the 80-90% if I would have been at Prague. But I disagree that it should be the base foundation of everything under the umbrella Media initiative because it provide too much complexity for simpler uses cases that can be met with File entity.

Since comment #6, I've been advocating a complementary approaches. I agree, now, that media could be more than files. What I'm saying is that files are often enough for a lot of people. The Media initiative should provide tools for these users too instead of focusing on the users with more complex needs and a larger definition of what a media is. This is doable, but not if an additional Media entity type is used as the foundation of everything Media.

The File entity provide an extendable OO layer to access and manipulate fields using APIs known by developers unfamiliar with lower level file handling. If Entity and Fields APIs are good to build the media layer, why aren't they for the file layers?

My suggestion is to base the browser layer on oEmbed (or another independent protocol) not on File entity, not on Media entity. This in order to allow 80-90% of the integration to stay the same while the 10-20% tied to the underlaying server side model can be swapped. Thus decoupling most of the browser layer from the server side, and even from Drupal itself. Could you explain what is broken with this approach, or if it has already been explained give a clear reference to that explanation because I don't see it here.

First of all I think that using file entity as backend storage for any media solution is simply a hack, it can obviously work (as in D7 media) but most of media resources are just not files and I think it is simply wrong to think of them as files and stores them in file_managed table and any solution based on this approach is just weird in mine opinion. It is an OK solution when your media resource is really a file and will always be a file, but everything else is a hack for me. Again this is just my opinion.

Second I really do not understand why so much complains about adding additional light media_entity layer which only job is to hold any possible and impossible storage media backend (file entity, youtube video, twitt, what ever...). Think about all possibilities that we will get with this unified approach.
As I see it media_entity is just very simple container for any possible media resource you wanna use and nothing else. It will not give you fancy UI, media browser or other stuff nor it job is to provide you with this. It will not limit you with any assumption how media resource is stored, what is actually a media resource and where it is stored (local or remote) and how you wanna use your media resources - which is good thing actually.
The way I see it media_entity is just an effort to standardize base media handling for D8. The more complex work is left to other contrib modules to do and to adapt to specific use case they wanna solve.

Also I don't see any big complexity addition with this approach - it is just a thin layer with API for unified managment of media resources and thats all, nothing fency or complex about it - its just simple entity with some helper API and that's it.

So I do not see any complexity for end users added - end users should not even know that media_entity module and it entity exist. It is a job of a contrib module that is build on media_entity to hide all that complexity from them and contrib should offer out of the box solution for end user.
For example I am maintainer of mediabox module - and there we have actually not one but two media entity - one like media_entity and one for media entity display. So it is two layers of complexity and not one, but end users will never see that because everything is hidden for them - all they see is image gallery with pluopload and crop integration and media browser that works out of the box. Now imagine that we are in D8 now and mediabox works with media_entity in the backend; some user is using mediabox for a while and then he decide that mediabox ui is not good and he wanna try scald - for him transition from mediabox to scald will be now much easier if both mediabox and scald use same backend. And this is just one example of many nice&cool stuff we will get if we all use standardized media handling backend - media_entity.

For developers again this is just simple entity that is holding media resources and nothing else. I don't see that it ads any complexity in theirs work, but actually it will make everybody life much easier if everybody use this standard.

I do not suggest to use File entity as storage back-end for any media solution. My suggestion is to use File entity as abstraction for any media solution that works with bytes streams and their meta-data. If a media is properly represented by a byte streams (an image, a video, a PDF document, etc.), then it should be handled through a File entity (even if wrapped by a Media entity). If a Media is not properly represented by a byte stream (a tweet, an image gallery, an article, etc.) then a File entity is not needed.

If files are enough for the end-user and the developer, (s)he should not be required to work with the Media entity. No matter how thin the layer is, it is an additional layer (s)he would rather not have to think about. Eventually, the Media entity abstraction will leak (all abstractions do) and the user or the developer will see and have to deal with the lower layers.

The overhead of having components designed to work with either File entity and Media entity could be limited. Either because they are designed to isolate the parts tied to one of them in swappable sub-components, or by designing them to consume interfaces for which File entity and Media entity adapters are provided. To continue with my WYSIWYG suggestion, the oEmbed endpoint and resources browser are swappable because the integration is build on oEmbed, not File entity, not Media entity. The embedding configuration widget is extensible, allowing any parameters to be added though custom and user-friendly UI elements.

That said, there is no reason to continue the discussion here for me. I believe it is clear that a Media entity type is needed ans should be defined (which is the purpose of this issue). Sorry for side-tracking the discussion.

@mongolito404 I think I understands now 50% of the things you are talking, sorry for that ;)

Didn't work with oEmbed standard before, after quick informing, as I see it its just one possible resource plugin that we could support as a media resource for our media_entity - am I correct here or totally talking nonsense?

I'm not sure using oEmbed as media resources make sense. oEmbed defines a protocol for a client to easily embed a resource identified by an URL in HTML. Using the resource URL, the client send a request to a oEmbed endpoint. For this request, oEmbed defines only two parameter for an oEmbed request, maxWidth and maxHeight. But client and oEmbed provider can support more parameters (so the protocol is extensible). A oEmbed response contains enough information to embed the resource in HTML. For an image, that's an HTTP(S) URL. For everything else, that's the HTML markup to embed the resource. To me, it make more sens to use oEmbed as the protocol used to get the HTML markup to embed a Media entity (which require each Media entity to have an URL). Note that while oEmbed was designed for HTTP, a fake PHP oEmbed endpoint could be used in when the HTML is generated server side.

Here is a link to oEmbed specification http://oembed.com/.

And spec there says that this standard supports 4 types (not just images): photo, video, link and rich.

So it is definitely look to me that this can be one of many resource plugins we can build in contrib space for media_entity.

It does in D7 for the current media-module https://drupal.org/project/oembed
It can indeed become one of the resource plugins.

Yes, I talked with CKEditor team at Prague and they said that they were developing a plugin based on oEmbed too. An example of multi-service oembed provider http://embed.ly/embed/features/providers (there is also a Scald provider for oEmbed https://drupal.org/sandbox/jagopian/1966468).

There are a few problems with oembed-as-media-provider though, but I think this is not a place to discuss.

Let's go back to the issue. So, for a Media entity, there are:
* In the base table:
- id
- uuid
- vid
- langcode
- bundle
- resource provider
* In the data/revision table:
- title
- base_id (fid for File entity provider, or file URI for any "stream wrapper" provider, or URL, or YouTube video ID... can be NULL - this field is for fast searching)
- authors
- publisher
- status
- created
- changed
- thumbnail (required, if we want some nice listings)
- data (serialized)

Hmmm for thumbnail not sure? As i see it we do not limit our media stuff only to pictures and videos, but theoretically we can reference anything. How we will produce thumbnail in that case.

Also I would like to be able to configure how this thumbnails are shown - for example in some media browser that is views based I want to be able to say for this listing I want thumbnails of this size over image style or something like that.

Not sure how to do this for now - what kind of model should we use.

Update: actuall why not having a display 'Thumbnail' for this - user can then change this to his own will?

Update2: also vid - do we want to have revision support out of the box or is this optional?

- Thumbnail: a normal image field (so, fid), with cardinality 1 (can be empty: use default thumbnail).
- Authors: the ones who own the authorship of the media.
- Publisher: in node it is node author - the one who create the entity.

About the base_id, resource provider or resource field, I'm not sure how to do it in D8 to make sense, and we still don't agree on what is a "resource field". I think it must be a required field with cardinality = 1 (one media entity has only one "core" media), and only attachable to media entity. I guess we need input from someone who is familiar with Drupal 8 entity system.

I still don't get the thumbnail. If I create a media entity item which is actually an image, then I can add a thumbnail if I need it somewhere. But isn't it possible to just use a different image style for the image field in a teaser display mode for listings?

Thumbnail field could be useful in a more specific use case, where you actually want to manually crop the image to a certain part of the actual image, or use a completely different image only for thumbnail. And for video fields it makes sense to have a separate thumbnail. But not a required field in my opinion.

Shouldn't the thumbnail be something provided by the resource provider, not the Media entity itself? When the thumbnail of a Media entity is requested, the Media entity ask its resource provider for its thumbnail. And if the resource provider does not provide an usable image, then a default placeholder image is used. Of course, the resource provider has access to the fully loaded Media entity when it has to provide its thumbnail so it may actually store the thumbnail in a (custom) field. But a YouTube resource provider could use (a cached copy of) the thumbnail already provided by YouTube.

Shouldn't the base_id field and the resource provider field be a unique resource field with two columns: provider and id (I'm not sure columns is the right term in D8)? The provider column reference the resource provider (likely a Plugin ID then), and id is a provider dependent string to identify a single resource. For instance, for a YouTube video media the value of its resource field would be array('provider' => 'youtube', 'id' => 'oHg5SJYRHA0'). For a local file media, the value of its resource field would be array('provider' => 'file_entity', 'id' => '25') (25 would be the fid of an existing file).

After rereading the discussion. If you define an entity type and its field, do not think (and thus talk) in term of table. Table a low-level when thinking in term of entities. I guess D8 has some concept of versioned entity (for revision) and that you could define which field of an entity are versioned and which fields are not versioned.

I used columns using italic, because that's how the subfield of a field are called in D7 (think the entity_id and entity_type of a entity reference). But a field (or property in D8) may or may not be stored in a database table.

Also entity versionning is probably not something you enable when wanted (opt-in), but likely something you disable when not wanted (opt-out). Even if it may be disable by default, it has to be included in the design from the start.

A typo